sap-fiori-mcp-server — Claude Code plugin: build SAP Fiori apps

[![Changelog](https://img.shields.io/badge/changelog-8A2BE2)](https://github.com/SAP/open-ux-tools/blob/main/packages/fiori-mcp-server/CHANGELOG.md) [![Github repo](https://img.shields.io/badge/github-repo-blue)](https://github.com/SAP/open-ux-tools/tree/main/packages/fiori-mcp-server)

# [`@sap-ux/fiori-mcp-server`](https://github.com/SAP/open-ux-tools/tree/main/packages/fiori-mcp-server)

This package includes a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for integration with AI coding assistants.

The server helps AI models create or modify SAP Fiori applications based on prompts, such as:

- _Please add a SAP Fiori elements list report app to my CAP project_
- _Generate a new CAP project and SAP Fiori app based on my_picture.png_
- _Generate a new SAP Fiori elements list report app for odata service `https://hostname:port/sap/opu/odata4/sap/my_v4_service?sap-client=000`_.

  ℹ️This prompt requires a saved SAP system connection by using the [Connection Manager for SAP Systems](https://marketplace.visualstudio.com/items?itemName=SAPOSS.sap-ux-sap-systems-ext) extension.
- _Add the FCL to the SAP Fiori elements app_
- _Enable initial load for the fiori app_

For the best experience we recommend using this server alongside [@cap-js/mcp-server](https://www.npmjs.com/package/@cap-js/mcp-server) and [@ui5/mcp-server](https://www.npmjs.com/package/@ui5/mcp-server).

## [Setup](#setup)

The server uses `stdio` transport and is launched via `npx` — no global installation required. Pick the section for your MCP client below.

> **Note:** Replace `<version>` with the specific version you want to pin to (e.g. `1.12.2`). The current release version is shown on the [npm page](https://www.npmjs.com/package/@sap-ux/fiori-mcp-server). Using a pinned version rather than `@latest` ensures reproducible behaviour and prevents untested updates from being picked up automatically.

### Claude Code

**Option A — CLI (recommended):**
```bash
claude mcp add fiori-mcp -- npx --yes @sap-ux/fiori-mcp-server@<version> fiori-mcp
```

**Option B — drop a `.mcp.json` file in your project root:**
```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes", "@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"]
    }
  }
}
```

### Cline

Open the Cline extension settings and add the server under **MCP Servers**:

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes", "@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"]
    }
  }
}
```

### Cursor

Edit (or create) the MCP config file for your scope:

- **Global:** `~/.cursor/mcp.json`
- **Project:** `.cursor/mcp.json` in your project root

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes", "@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"]
    }
  }
}
```

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes", "@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"]
    }
  }
}
```

### Other clients

For any other MCP client, use the following `npx`-based configuration:

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes", "@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"]
    }
  }
}
```

### Global npm install (any client)

If you prefer **not** to use `npx`, install the package globally first:

```bash
npm install -g @sap-ux/fiori-mcp-server
```

Then use `fiori-mcp` as the command (no `args` needed):

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "fiori-mcp"
    }
  }
}
```

## [Rules](#rules)

The following rules help guide the AI model to use the server correctly. Add them to your system prompt or rules file:

- **Claude Code:** `AGENTS.md` or `CLAUDE.md` in your project root
- **Cline:** Custom Instructions in the Cline extension settings
- **Cursor:** `.cursorrules` in your project root
- **Windsurf:** Global Rules or project-level `.windsurfrules`

```markdown
## Rules for creation or modification of SAP Fiori elements apps

- When asked to create an SAP Fiori elements app check whether the user input can be interpreted as an application organized into one or more pages containing table data or forms, these can be translated into a SAP Fiori elements application, else ask the user for suitable input.
- The application typically starts with a List Report page showing the data of the base entity of the application in a table. Details of a specific table row are shown in the ObjectPage. This first Object Page is therefore based on the base entity of the application.
- An Object Page can contain one or more table sections based on to-many associations of its entity type. The details of a table section row can be shown in an another Object Page based on the associations target entity.
- The data model must be suitable for usage in a SAP Fiori elements frontend application. So there must be one main entity and one or more navigation properties to related entities.
- Each property of an entity must have a proper datatype.
- For all entities in the data model provide primary keys of type UUID.
- When creating sample data in CSV files, all primary keys and foreign keys MUST be in UUID format (e.g., `550e8400-e29b-41d4-a716-446655440001`).
- When generating or modifying the SAP Fiori elements application on top of the CAP service use the Fiori MCP server if available.
- When attempting to modify the SAP Fiori elements application like adding columns you must not use the screen personalization but instead modify the code of the project, before this first check whether an MCP server provides a suitable function.
- When previewing the SAP Fiori elements application use the most specific `npm run watch-*` script for the app in the `package.json`.
```

## [Available Tools](#available-tools)

#### `search_docs`
Searches SAP Fiori elements, Annotations, UI5, OPA5 Guides, SAP Fiori tools documentation for the given query.

Note: the results are based on the most recent indexed version of UI5 documentation

> **First-use download:** `search_docs` uses a local text-embedding model (`all-MiniLM-L6-v2`, ~86 MB) for semantic search. The model is downloaded from HuggingFace Hub on first use and cached locally (location follows the `HF_HOME` / `TRANSFORMERS_CACHE` environment variables, defaulting to `~/.cache/huggingface/hub`). Subsequent starts load the model from the cache with no network access required.

#### `list_fiori_apps`
Scans a specified directory to find existing SAP Fiori applications that can be modified.

#### `list_sap_systems`
Lists all SAP systems stored in the user's environment (e.g. SAP Fiori tools system store). Use this when the user references a SAP system by name before calling `download_odata_service_metadata` or generating a Fiori application.

#### `download_odata_service_metadata`
Downloads the EDMX metadata of a specific OData service from a SAP system and saves it as `metadata.xml`. Use this before calling `generate_fiori_app_odata` when the user provides a SAP system reference or service URL.

#### `generate_fiori_app_odata`
Generates a new SAP Fiori UI application for OData (non-CAP) projects, for example [ABAP RESTful Application Programming Model](https://pages.community.sap.com/topics/abap/rap)-based OData services.

#### `generate_fiori_app_cap`
Generates a new SAP Fiori UI application within an existing [SAP Cloud Application Programming Model (CAP)](https://cap.cloud.sap/) project.

#### `list_functionality` (Step 1 of 3)
Gets the list of supported **modification** functionalities for an existing SAP Fiori application. Requires a valid absolute path to the application.

The supported modifications are:

- Adding and deleting pages from an app
- Adding and modifying controller extensions
- Modifying `manifest.json` properties depending on the app, for example, adding a layout based on the flexibility of the programming model or enabling initial load

#### `get_functionality_details` (Step 2 of 3)
Gets the required parameters and detailed information for a specific functionality to modify an existing SAP Fiori application.

#### `execute_functionality` (Step 3 of 3)
Executes a specific functionality to modify an existing SAP Fiori application with provided parameters.

## [Logging](#logging)

By default, logging is enabled at the `error` level. To adjust the log level or disable logging completely, you can use the `env` property in your configuration.

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes","@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}
```
The following log levels are supported: `off`, `error`, `warn`, `info`, `debug`, and `verbose`.

The logs are stored in the file system at `~/.fioritools/fiori-mcp-server.log`


## [Handling Self-Signed SSL Certificates](#handling-self-signed-ssl-certificates)

If you need the MCP server to connect to an OData server using a self-signed SSL certificate, you can use one of the following methods.

This is useful when encountering errors such as: `unable to get local issuer certificate`

### Option 1: Add Custom CA Certificate (Recommended)

Set the `NODE_EXTRA_CA_CERTS` environment variable to the path of your CA certificate file. Node.js supports multiple file extensions (`.pem`, `.crt`, `.cer`, `.cert`).

**Example Configuration:**

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes", "@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/path/to/your/certificate.crt"
      }
    }
  }
}
```

**Windows Example:**
```json
"env": {
  "NODE_EXTRA_CA_CERTS": "C:\\temp\\certs\\CustomCA.crt"
}
```

**macOS/Linux Example:**
```json
"env": {
  "NODE_EXTRA_CA_CERTS": "/Users/username/certs/Custom_CA.crt"
}
```

### Option 2: Bypass SSL Validation (Not Recommended)

> ⚠️ **Security Warning**: Setting `NODE_TLS_REJECT_UNAUTHORIZED=0` disables all SSL certificate validation and poses a significant security risk. Only use this in non-production environments.

```json
{
  "mcpServers": {
    "fiori-mcp": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["--yes", "@sap-ux/fiori-mcp-server@<version>", "fiori-mcp"],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}
```

### Additional Resources

- [Node.js Documentation - NODE_EXTRA_CA_CERTS](https://nodejs.org/api/cli.html#node_extra_ca_certsfile)
- [SAP Fiori tools - SSL Certificate Handling](https://github.com/SAP-samples/fiori-tools-samples/tree/main/misc/sslcerts)



## [Telemetry](#telemetry)

You can enable and disable the collection of analytics. By default, non-personally identifiable information is used to help understand how you use the product to improve the Fiori MCP Server. In case you want to opt-out there exist two ways to disable the telemetry.

### Method 1: Configuration File

Create or change the file `~/.fioritools/telemetrysettings.json`:

```json
{
  "telemetrysettings": {
    "telemetrySetting": {
      "enableTelemetry": false
    }
  }
}
```

Set `enableTelemetry` to `false` to disable telemetry collection.

### Method 2: Environment Variable

Set the environment variable `SAP_UX_FIORI_TOOLS_DISABLE_TELEMETRY` to `true`:

```bash
export SAP_UX_FIORI_TOOLS_DISABLE_TELEMETRY=true
```

Setting this environment variable will disable the telemetry client.

## Code of Conduct

Everyone participating in this joint project is welcome as long as our [Code of Conduct](https://github.com/SAP/open-ux-tools/blob/main/docs/CODE_OF_CONDUCT.md) is being adhered to.

## Licensing

Please see our [LICENSE](./LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the [REUSE tool](https://api.reuse.software/info/github.com/SAP/open-ux-tools).