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

Variable / Flag	Default	Description
--tool-timeout / SAP_MCP_TOOL_TIMEOUT	30 (seconds)	Time budget for a whole tool call, however many SAP requests it makes. On expiry the client gets a valid MCP response with truncated: true and a plain-language reason — never a hanging connection. Paginated reads return the pages fetched so far. 0 disables the budget (logged as a warning at startup)
SAP_HTTP_TIMEOUT_MS	30000	Timeout for a single outbound SAP request (ms). Hanging gateways fail fast with a structured TIMEOUT error instead of stalling the n8n agent. Capped by whatever is left of the tool budget above
--cache-dir / SAP_CACHE_DIR	(unset = in-memory only)	Persist the catalog and metadata caches to disk so a restart does not refetch them. Without it every restart re-reads the full catalog — on a system with 1222 services that is the cold start that breaks client timeouts. n8n evicts its own client entry on a transport error, so restarts are not rare
SAP_CA_CERT	(unset)	Path to the root CA that signs your SAP certificate — the documented way past a corporate PKI. Mirrored into NODE_EXTRA_CA_CERTS. Prefer this over SAP_TLS_VERIFY=false, which disables the check rather than solving it
--concurrency / SAP_CONCURRENCY	5	Upper bound on simultaneous SAP requests where several are unavoidable
--allow-write / SAP_MCP_ALLOW_WRITE	(unset = read-only)	Since 0.2.2 the server is read-only by default. sap_create, sap_update, sap_delete, sap_function and sap_idoc_send are not registered at all until you set this — a tool an agent cannot see is a tool it cannot call by accident. --read-only is still accepted and now simply describes the default
SAP_JWT_ISSUER	(unset = no verification)	Issuer whose JWKS is used to verify incoming user tokens. Without it tokens are only decoded, and the resulting identity is marked verified: false — safe to forward to SAP (SAP verifies itself), but not safe to base a local decision on. With it, a token failing verification is rejected with 401 rather than silently downgraded to the technical user
SAP_WEBHOOK_SECRET / --webhook-secret	(unset = open + startup warning)	Shared secret for the inbound IDoc webhook. Accepts Authorization: Bearer <secret> or HTTP Basic auth whose password equals the secret (matches SAP SM59 HTTP destinations)
SAP_WEBHOOK_HOST / --webhook-host	all interfaces	Bind address of the standalone IDoc webhook (stdio mode). Set 127.0.0.1 behind a reverse proxy
SAP_WEBHOOK_MAX_BODY_BYTES	10485760 (10 MB)	Reject larger IDoc payloads with 413 before they are buffered in memory

In HTTP transport mode the /idoc route is mounted on the MCP port: with --webhook-secret it authenticates independently of --api-key (so SAP's Basic auth works while n8n uses the Bearer key); without it, it falls under --api-key if set — and is open if neither is configured (the server logs a warning at startup).

Both timeouts must stay below the smallest client limit in your setup. Measured against a production S/4HANA behind Cloudflare: Cloudflare aborts at 100 s (524), n8n's MCP client transport at 300 s. A budget above the smallest limit never takes effect, because the client gives up first.

Tracing a slow tool call

Every tool call logs one line on completion, carrying a correlation id that also appears on each SAP request it triggered:

{"correlationId":"a3f19c8b2d04","tool":"sap_discover_services","outcome":"ok","durationMs":842,"sapCalls":1,"resultBytes":18422}

grep a3f19c8b2d04 then shows the full story of that one call — including how many SAP requests it produced. outcome is one of ok, error, timeout (budget expired) or aborted (client disconnected).

level: 50 means something is actually wrong. Expected non-2xx responses — the 404s from the catalog path probing and from the V4 catalog attempt on systems that have none — are logged at info with "expected": true, not at error. Measured on a production system: over 96 hours of runtime that false alarm was the only error-level entry in the log. Alerting on level: 50 is therefore meaningful; before, it produced nothing but noise.

When something breaks

test-connection walks the whole chain and reports the first failing stage — DNS, TLS (including the certificate chain), authentication, client (Mandant), catalog. Stages after the failure are reported as skipped, never as passed. The same five stages are logged once at startup, so the container log shows the state of the connection without calling anything.

Every error response carries a classification, the SAP error code where one exists, a plain-language message and the next action — no tool answers with "Unknown error". Three cases that used to cost a separate diagnosis each:

What SAP returns	What the server tells you
403 with /IWFND/MED/170	The service is not registered — activate it in /IWFND/MAINT_SERVICE. Not an authorization problem, despite the 403
401 with an HTML logon page	Is sap-client set? Without it a client-dependent Gateway rejects the logon in a way that looks like a wrong password
UNABLE_TO_GET_ISSUER_CERT_LOCALLY	The certificate chain is incomplete; supply the root CA via SAP_CA_CERT. The message names the issuing CA

If SAP_TLS_VERIFY=false is in effect, every tool result carries a warning about it — not just the startup log. A disabled check that nobody sees after the first day tends to stay for years; on the production system that prompted this work it was set, and nobody noticed.

Streamable HTTP is stateless

--transport http serves MCP in stateless mode: every request is self-contained and the server neither issues nor expects an mcp-session-id header. There is no server-side session to resume, so a client may reconnect at any time without losing state.

Clients that require a session id — they read mcp-session-id from the initialize response and send it back on subsequent requests — will fail against this server. The n8n MCP Client, Claude Desktop, and the MCP Inspector all work without it.

The legacy --transport sse mode is different: it keeps a per-connection session and expects a ?sessionId= query parameter on /messages. Prefer http for new setups.

Several SAP systems: destinations.json

The SAP_* variables describe one SAP system. To run one server against several — a production system next to a test client, or several customers' systems behind one n8n — put the connections into a destinations.json and point the server at it:

guniweb-sap-mcp --transport http --port 8808 --destinations /config/destinations.json
# or: SAP_MCP_DESTINATIONS=/config/destinations.json

{
  "version": 1,
  "destinations": {
    "default": {
      "baseUrl": "https://s4prod.example.com",
      "authType": "basic",
      "username": "MCP_USER",
      "password": "${S4PROD_PASSWORD}",
      "sapClient": "100"
    },
    "s4test": {
      "baseUrl": "https://s4test.example.com",
      "authType": "basic",
      "username": "MCP_USER",
      "password": "${S4TEST_PASSWORD}",
      "sapClient": "200"
    }
  }
}

• One entry = one connection. Every entry accepts exactly the fields the SAP_* variables accept (authType and its credentials, sapClient, baseUrl) — all authentication types work per destination.
• Personal SAP login per request — "authType": "user-basic": the destination knows system and client only; SAP user and password come with each request (X-SAP-Username/X-SAP-Password, in n8n the credential of the GuniWeb SAP node). Everyone acts in SAP as themselves — authorizations, change documents and audit trail on the real user, no shared technical account. No fallback to a technical user (401 without a login), caches per user, passwords never logged. HTTP transport only. Details in the setup guide.
• Secrets stay out of the file. Any string may contain ${VARIABLE}; it is resolved from the environment at load time (Docker secrets, .env). A placeholder that cannot be resolved makes the file invalid — an empty password would otherwise surface as a misleading 401 from SAP.
• Hot reload. The file is watched; a change is picked up on the next request, no restart. kill -HUP <pid> forces a reload. An invalid file never replaces the running configuration — the error is logged and the last valid one stays in force.
• Backwards compatible. Without --destinations nothing changes: the SAP_* variables are the single destination default. With the file, SAP_* (if set) is added as default unless the file defines one — so an installation can migrate without a gap.
• Which destination answers? Without a token: the one named default (or the only one). With a token: the token's destination — see below.

Tokens: one Bearer value per n8n credential selects the system. The n8n MCP Client sends exactly one Authorization header, so a token does two jobs at once — it authenticates the request and picks the destination. SAP passwords never leave the server; n8n only holds the token.

{
  "version": 1,
  "destinations": { "s4prod": { "...": "..." }, "s4test": { "...": "..." } },
  "tokens": [
    { "hash": "sha256:9f2c…", "destination": "s4prod", "label": "n8n prod workflows" },
    { "hash": "sha256:1a7e…", "destination": "s4test", "label": "n8n dev", "revoked": false }
  ]
}

• The file holds only the SHA-256 hash; the plain token (gsm_<destination>_<random>) is printed once by tokens issue and cannot be recovered afterwards. Put it into an n8n Bearer Auth credential on the MCP Client node. As soon as at least one token exists, requests without a valid token get 401 — --api-key keeps working alongside and serves the default destination.
• Lookup is constant-time over all entries; "revoked": true disables a token on the next request (hot reload, no restart). After 10 failed attempts within a minute the client address gets 429 with Retry-After — also for a valid token — as a brake on guessing (a reverse proxy with a real rate limit is still the right place for that). Tokens are never written to the log; rejections are logged with address and reason. Managing the file — no hand-editing needed. The same binary carries the admin commands; every command validates the result exactly like the server does before writing (never leaves an unloadable file), writes atomically, and a running server picks the change up on the next request:

export SAP_MCP_DESTINATIONS=/config/destinations.json      # or --destinations <path> on each call

guniweb-sap-mcp destinations add s4prod --base-url https://s4prod.example.com --auth-type basic \
    --username MCP_USER --password '${S4PROD_PASSWORD}' --sap-client 100
guniweb-sap-mcp destinations add legacy --from-env         # copy the current SAP_* environment (migration)
guniweb-sap-mcp destinations list                          # names, URLs, auth type, client, token count — never secrets

guniweb-sap-mcp tokens issue s4prod --label "n8n prod" --read-only --tiers core,odata
#   → prints the plain token ONCE on stdout (everything else goes to stderr, so TOKEN=$(…) works)
guniweb-sap-mcp tokens list                                # label, destination, hash prefix, policy, status
guniweb-sap-mcp tokens revoke "n8n prod"                   # by label or ≥ 8 hex chars of the hash
guniweb-sap-mcp destinations remove s4test [--force]       # refuses while tokens point at it, unless --force

--set field=value covers any auth type (--auth-type oauth2 --set clientId=… --set clientSecret='${BTP_SECRET}' --set tokenServiceUrl=…); ${ENV_VAR} values are checked against the current environment (--allow-missing-env to skip, e.g. when the variable only exists inside the container). In Docker, run the commands inside the container so they see the same file and environment: docker compose exec sap-mcp guniweb-sap-mcp tokens issue s4prod.

• Per-token permissions — "policy": { "readOnly": true, "tiers": ["core", "odata"] }. A policy only ever restricts: readOnly: true hides the write tools for that token even when the server runs with --allow-write (readOnly: false cannot open a read-only server), and tiers is a ceiling — tiers outside it are invisible for that token and sap_enable_tools cannot switch them on. tools/list is filtered per request, so an agent on a read-only token never sees sap_create in the first place.

Admin API — the same operations over HTTP (self-service). With --admin-token <secret> (or SAP_MCP_ADMIN_TOKEN, at least 16 characters, e.g. openssl rand -base64 32) the server exposes the CLI's operations under /admin — for an n8n workflow that provisions a new customer's access, a script, or a person with curl, without a shell on the host:

guniweb-sap-mcp --transport http --port 8808 --destinations /config/destinations.json --admin-token "$ADMIN"

A="Authorization: Bearer $ADMIN"; J="Content-Type: application/json"; U=http://localhost:8808/admin
curl -H "$A" $U/destinations                                    # list — never secrets
curl -H "$A" -H "$J" -X PUT $U/destinations/s4prod \           # create (201) or replace (200)
     -d '{"baseUrl":"https://s4prod.example.com","authType":"basic","username":"MCP_USER","password":"${S4PROD_PASSWORD}","sapClient":"100"}'
curl -H "$A" -H "$J" -X POST $U/tokens \                       # → { "token": "gsm_s4prod_…", … } — shown ONCE
     -d '{"destination":"s4prod","label":"n8n prod","readOnly":true,"tiers":["core","odata"]}'
curl -H "$A" $U/tokens                                          # label, destination, hash prefix, policy, status
curl -H "$A" -X DELETE "$U/tokens/n8n%20prod"                   # revoke by label or hash prefix
curl -H "$A" -X DELETE "$U/destinations/s4test?force=true"      # remove; without force it refuses while tokens exist

• Separate keys, separate doors. The admin secret opens only /admin; the n8n tokens and --api-key open only /mcp. A leaked n8n token cannot mint further access, an admin secret cannot read SAP data. Wrong secrets are counted per client address (429 after 10 failures per minute); every change is logged with action, target and client address — never the token, never the secret. Without --admin-token, /admin/* answers 404.
• Effective immediately. Every write validates like the CLI, writes atomically and reloads the running configuration before answering ("reloaded": true). If the server cannot load what was written — typically a ${VAR} that only your shell knows, written with ?allowMissingEnv=true — the answer says "reloaded": false with the errors, and the last valid configuration stays in force.
• Bootstrap without any SAP configuration. With --admin-token the server starts even if destinations.json does not exist yet and no SAP_* is set: /mcp answers 503 until the first destination (and a token, or a destination named default) has been created through the API. docker run … -e SAP_MCP_ADMIN_TOKEN=… -e SAP_MCP_DESTINATIONS=/config/destinations.json is a complete first start.
• Put the API behind the same reverse proxy/TLS as /mcp; the admin secret travels as a Bearer header like any other credential.

4. Use with n8n