GuniWeb SAP S/4HANA & ECC MCP Server

Designed for n8n, usable from any MCP host. Free to use — built and maintained by GuniWeb.

Connect n8n workflows to SAP S/4HANA and ECC via OData V2, V4, IDocs, and RFC/BAPI using the Model Context Protocol (MCP). Made for AI-assisted, human-governed workflows: the workflow author decides which SAP APIs are called and in what order; the LLM extracts, maps and fills in parameters. Writes are off by default and switched on explicitly, per server and per token.

graph LR
    n8n["n8n workflow<br/>AI-assisted, human-governed"] -->|MCP Protocol| MCP["guniweb-sap-mcp<br/>22 Tools &bull; 8 Auth Types"]
    MCP -->|"OData V2/V4<br/>IDoc XML<br/>RFC/BAPI"| SAP["SAP S/4HANA & ECC"]
    MCP -->|"OAuth2 / JWT"| BTP["SAP BTP"]
    BTP --> SAP

    style n8n fill:#4a90d9,color:#fff,stroke:#3a7bc8
    style MCP fill:#2d2d2d,color:#fff,stroke:#555
    style SAP fill:#1a6fb5,color:#fff,stroke:#0f5a9d
    style BTP fill:#e8a317,color:#fff,stroke:#c88d14

Features

OData & IDoc

• OData V2 + V4 CRUD -- Read, query, create, update, delete with auto version detection
• Deep Insert -- Create parent + child entities in one request
• Function Imports (V2) & Actions/Functions (V4) -- Trigger SAP business logic
• Batch Operations -- Multiple operations in a single $batch request
• NL-to-OData Query -- Natural language queries converted to structured OData filters
• IDoc Send & Receive -- HTTP/XML based, no RFC dependency

Discovery & Intelligence

• Service Discovery -- Auto-discover OData services with 16 business domain categories
• Progressive Metadata -- Service catalog -> entity sets -> properties -> query
• Smart Query Routing -- Domain-based routing resources for LLM tool selection
• Decision-Tree Tool Descriptions -- "When to use / When NOT to use" blocks guide LLMs

Governed tool visibility

• 4-Tier Tool Registry -- Core / OData / IDoc / RFC tiers with on-demand activation
• sap_enable_tools -- LLMs activate additional tool tiers at runtime, within the limits you set
• Read-only by default (since 0.2.2) -- write tools require --allow-write
• Per-token policy (0.3.0) -- readOnly and tool-tier ceilings per Bearer token, only ever more restrictive
• IDoc / RFC auto-disable -- tools hidden when the corresponding configuration is missing
• MCP Annotations -- readOnlyHint, destructiveHint, idempotentHint on all 22 tools

Authentication (8 Types)

graph TB
    subgraph Technical["Technical User Auth"]
        basic["basic<br/><i>Direct S/4HANA</i>"]
        userbasic["user-basic<br/><i>Personal SAP login per request</i>"]
        oauth2["oauth2<br/><i>BTP Client Credentials</i>"]
        apikey["apikey<br/><i>Sandbox / Testing</i>"]
    end
    subgraph Enterprise["Enterprise Auth (OIDC)"]
        ias["ias<br/><i>SAP IAS Token</i>"]
        xsuaa["xsuaa<br/><i>SAP XSUAA Token</i>"]
    end
    subgraph Principal["Principal Propagation<br/><i>End-user identity forwarded to SAP</i>"]
        btp["btp-principal<br/><i>JWT Bearer Exchange<br/>via Destination Service</i>"]
        saml["saml-bearer<br/><i>SAML 2.0 Assertion<br/>+ RSA-SHA256 Signing</i>"]
    end

    style Technical fill:#2a5f8f,color:#fff,stroke:#1a4f7f
    style Enterprise fill:#5b8c5a,color:#fff,stroke:#4b7c4a
    style Principal fill:#8b5e3c,color:#fff,stroke:#7b4e2c

Infrastructure

• Three Transport Modes -- stdio, Streamable HTTP, SSE
• Named destinations (0.3.0) -- one server, several SAP systems; a Bearer token per n8n credential selects the system and its permissions. Static API key still supported
• Docker Ready -- Docker Compose for n8n + SAP MCP sidecar
• Zero telemetry -- the server talks to the SAP/BTP endpoints you configure and to nothing else. No usage statistics, no update checks, no crash reports
• 1267 Tests -- Unit, integration, E2E with CI/CD via GitHub Actions

Quick Start

Try it without an SAP system: --demo

No SAP system at hand? Start the server against a built-in mock S/4HANA and try every tool from n8n or any MCP client:

npx guniweb-sap-mcp --demo                                   # stdio — n8n MCP Client in command mode
npx guniweb-sap-mcp --demo --transport http --port 8808      # HTTP — n8n MCP Client with URL http://localhost:8808/mcp
npx guniweb-sap-mcp --demo --allow-write                     # also try sap_create / sap_update / sap_delete / sap_batch

The demo starts an in-memory OData V2 gateway on localhost (three services with real SAP field names — API_BUSINESS_PARTNER, API_SALES_ORDER_SRV, API_PRODUCT_SRV; ~20 business partners, 15 sales orders with items, 10 products) and points the server at it. It behaves like a Gateway where it matters: catalog discovery, $metadata, $filter/$expand/paging, CSRF tokens, ETags, deep insert, function imports, $batch with changesets, SAP-style error payloads. Sample data only — nothing is real, nothing leaves your machine, and changes are gone when the process ends. Also SAP_MCP_DEMO=true (e.g. in Docker). A workflow you build against the demo runs against a real system after you replace --demo with your SAP_* configuration.

1. Install

npm install -g guniweb-sap-mcp

Or run it as a container: docker run --rm -p 8808:8808 -e SAP_MCP_DEMO=true ghcr.io/guniweb/guniweb-sap-mcp:latest

2. Configure

export SAP_BASE_URL=https://your-sap-system.example.com
export SAP_AUTH_TYPE=basic
export SAP_USERNAME=your-user
export SAP_PASSWORD=your-password
export SAP_CLIENT=100   # do not omit: without it a client-dependent Gateway
                        # answers 401 "Anmeldung fehlgeschlagen", which looks
                        # like a wrong password but is not one

3. Run

# stdio (default) -- for n8n MCP Client in command mode
guniweb-sap-mcp

# HTTP -- for n8n MCP Client in URL mode or Docker
guniweb-sap-mcp --transport http --port 8808

# With tool tier control
guniweb-sap-mcp --transport http --port 8808 --tiers core,odata
guniweb-sap-mcp --transport http --port 8808 --allow-write   # writes are OFF by default

# Production: authenticate the MCP endpoint AND the inbound IDoc webhook
guniweb-sap-mcp --transport http --port 8808 --api-key <mcp-key> --webhook-secret <idoc-secret>

Run as a container

# Look around first — mock S/4HANA inside the container, no SAP system needed
docker run --rm -p 8808:8808 -e SAP_MCP_DEMO=true ghcr.io/guniweb/guniweb-sap-mcp:latest

# Against a real system (pin the version in production)
docker run -d --name sap-mcp -p 8808:8808 --env-file .env \
  ghcr.io/guniweb/guniweb-sap-mcp:<version>

# Flags go straight to the server — writes stay off unless you say so
docker run -d -p 8808:8808 --env-file .env \
  ghcr.io/guniweb/guniweb-sap-mcp:<version> --allow-write

The image is built from the published npm package, not from a second build path — what runs in the container is the artifact you would have installed with npm install, so the two cannot drift apart. HTTP transport on port 8808 is the default inside the image (SAP_MCP_TRANSPORT / SAP_MCP_PORT); it runs as a non-root user, answers a health check on /healthz, and is published for linux/amd64 and linux/arm64 with build provenance.

Not included: RFC/BAPI. That path needs the SAP NW RFC SDK, which SAP licenses to customers only and which therefore cannot ship in a public image. Everything else — OData V2/V4, IDoc over HTTP/XML — works. For RFC, install the SDK on the host and run the server from npm (Setup for SAP ECC).

A docker-compose.yml that puts n8n next to the server is in the repository.

Production hardening