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: 5