guniweb-sap-mcp

v0.2.1

Published

a month ago

GuniWeb SAP S/4HANA & ECC MCP Server -- OData V2/V4, IDoc, and RFC/BAPI for n8n

0High
0Medium
0Low

jon_hartf

mcp mcp-server sap s4hana odata idoc n8n model-context-protocol integration erp

GuniWeb SAP S/4HANA & ECC MCP Server

Designed for n8n, usable from any MCP host

Connect n8n workflows to SAP S/4HANA and ECC via OData V2, V4, IDocs, and RFC/BAPI using the Model Context Protocol (MCP).

graph LR
    n8n["n8n AI Agent<br/>+ LLM"] -->|MCP Protocol| MCP["guniweb-sap-mcp<br/>22 Tools &bull; 7 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

Tool Visibility (v1.5)

3-Tier Tool Registry -- Core / OData / IDoc tiers with on-demand activation
sap_enable_tools -- LLMs activate additional tool tiers at runtime
--read-only Mode -- Hide all write/destructive tools
IDoc Auto-Disable -- IDoc tools hidden when no IDoc config present
MCP Annotations -- readOnlyHint, destructiveHint, idempotentHint on all 17 tools

Authentication (7 Types)

graph TB
    subgraph Technical["Technical User Auth"]
        basic["basic<br/><i>Direct S/4HANA</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
API Key Protection -- Secure HTTP transport with Bearer token
Docker Ready -- Docker Compose for n8n + SAP MCP sidecar
918 Tests -- Unit, integration, E2E with CI/CD via GitHub Actions

Quick Start

1. Install

npm install -g guniweb-sap-mcp

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

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 --read-only

4. Use with n8n

Add an AI Agent node with an MCP Client Tool sub-node
Set the MCP Client URL to http://sap-mcp:8808/mcp (Docker) or http://localhost:8808/mcp
The AI agent discovers SAP tools automatically and can query, create, update SAP data

Setup for SAP ECC

ECC NetWeaver backends require additional setup beyond the Quick Start. The MCP server supports ECC 6.0+ (EHP 7+) for OData V2, OData V4, IDoc HTTP/XML, and RFC/BAPI. Cloud-only S/4HANA tenants do not need this section.

1. Activate NetWeaver Gateway

In transaction SICF, activate the standard ICF services under /sap/opu/odata/. Then use transaction /IWFND/MAINT_SERVICE to register the OData services you want to expose.

The MCP server's catalog auto-discovery (Phase 23) probes three paths in sequence and caches the first 200 hit:

/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/ServiceCollection (S/4HANA default)
/sap/opu/odata/iwfnd/CATALOGSERVICE;v=2/ServiceCollection (lower-case ECC)
/sap/opu/odata/IWFND/CATALOGSERVICE/ServiceCollection (ECC EHP 7 v=1)

Override via ODATA_V2_CATALOG_PATH if your gateway uses a non-standard mount.

2. Install SAP NW RFC SDK (RFC/BAPI tools only)

Required for the rfc tool tier. Skip this step if you only use OData or IDoc.

Linux:

tar xzf nwrfcsdk_linux.tgz -C /usr/sap/
export LD_LIBRARY_PATH=/usr/sap/nwrfcsdk/lib:$LD_LIBRARY_PATH
npm install node-rfc

macOS:

tar xzf nwrfcsdk_darwin.tgz -C /usr/sap/
export DYLD_LIBRARY_PATH=/usr/sap/nwrfcsdk/lib:$DYLD_LIBRARY_PATH
npm install node-rfc

node-rfc is declared as optionalDependencies -- if the SDK is missing, the server logs a Pino warning at startup and the RFC tier is skipped. OData and IDoc tools continue to work.

3. ECC-Specific Environment Variables

In addition to the variables documented in Quick Start:

| Variable | Required | Description | |---------------------------|------------------------|--------------------------------------------------------------------------------------------| | ODATA_V2_CATALOG_PATH | No (auto-discover) | Override catalog path, e.g. /sap/opu/odata/iwfnd/CATALOGSERVICE;v=2/ServiceCollection | | SAP_TLS_VERIFY | No (default true) | Set to false to disable TLS certificate verification for self-signed-cert ECC scenarios | | SAP_CLIENT_CERT_PATH | For X.509 client-cert | Path to PEM-encoded client certificate, e.g. /etc/sap/client.crt | | SAP_CLIENT_KEY_PATH | For X.509 client-cert | Path to PEM-encoded private key (optional passphrase via prompt) | | SAP_SNC_QOP | For SNC (RFC) | SNC Quality-of-Protection level: 1 (auth-only), 2 (integrity), 3/8/9 (encryption) | | SAP_SNC_MYNAME | For SNC (RFC) | Local SNC name, e.g. p:CN=mcp-server, O=GuniWeb | | SAP_SNC_PARTNERNAME | For SNC (RFC) | Backend SNC name, e.g. p:CN=SAPSERVER, O=ACME | | SAP_SNC_LIB | For SNC (RFC) | Path to SNC library (.so / .dylib / .dll), e.g. /usr/sap/sapcrypto/libsapcrypto.so |

Available Tools (22)

Core Tier (always active)

| Tool | Description | |------|-------------| | test-connection | Test connectivity to SAP (pings catalog service) | | sap_list_services | List entity sets in an OData service | | sap_discover_services | Discover all services with category filtering and search | | sap_get_metadata | Inspect entity types, properties, keys (with search filter) |

OData Tier (active by default)

| Tool | Description | |------|-------------| | sap_read | Read a single entity or collection | | sap_query | Query with OData $filter, $select, $expand, pagination | | sap_nl_query | Natural language query with structured filters | | sap_create | Create entities (supports deep insert + draft services) | | sap_update | Update entities (automatic ETag handling) | | sap_delete | Delete entities (automatic ETag handling) | | sap_function | Call V2 function imports or V4 actions/functions | | sap_batch | Execute multiple operations in a single batch |

IDoc Tier (on-demand via `sap_enable_tools`)

| Tool | Description | |------|-------------| | sap_idoc_send | Send IDoc to SAP via HTTP/XML | | sap_idoc_list_received | List received IDocs from webhook | | sap_idoc_status | Check IDoc processing status | | sap_idoc_discover | Discover available IDoc types |

RFC Tier (on-demand via `sap_enable_tools`, requires SAP NW RFC SDK)

| Tool | Description | |------|-------------| | sap_rfc_call | Call any RFC-enabled function module with zod-validated parameters | | sap_rfc_metadata | Fetch function-module signature (imports/exports/tables/exceptions) | | sap_bapi_call | Invoke a BAPI, parse BAPIRET2 return tables, pin connection for follow-up commit | | sap_bapi_commit | Invoke BAPI_TRANSACTION_COMMIT on the pinned session | | sap_rfc_search_functions | Find function modules by name pattern via RFC_FUNCTION_SEARCH |

Meta Tool

| Tool | Description | |------|-------------| | sap_enable_tools | Activate/deactivate tool tiers at runtime |

Architecture

graph TB
    subgraph n8n["n8n"]
        Agent["AI Agent + LLM"]
        MCPClient["MCP Client Tool"]
        Agent --> MCPClient
    end

    subgraph Server["guniweb-sap-mcp"]
        Transport["Transport<br/>stdio | HTTP | SSE"]
        UserCtx["UserContext<br/>Extraction"]
        Registry["ToolRegistryManager<br/>Core | OData | IDoc"]
        Tools["17 MCP Tools<br/>3 Resources &bull; 3 Prompts"]
        OData["ODataClient<br/>V2/V4 Auto-Detect"]
        Discovery["Service Discovery<br/>16 Domain Categories"]
        NLQuery["NL-to-OData<br/>Filter Builder"]
        HTTP["SapHttpClient<br/>CSRF &bull; Redirect &bull; Auth"]
        Auth["Auth Layer<br/>7 Auth Types"]
        Cache["Per-User Token Cache<br/>LRU &bull; SHA-256"]

        Transport --> UserCtx
        Transport --> Registry
        Registry --> Tools
        Tools --> OData
        Tools --> Discovery
        Tools --> NLQuery
        OData --> HTTP
        Discovery --> HTTP
        NLQuery --> OData
        HTTP --> Auth
        Auth --> Cache
    end

    subgraph SAP["SAP Backend"]
        S4["S/4HANA<br/>OData V2/V4"]
        IDoc["IDoc<br/>HTTP/XML"]
        BTPSuite["BTP Integration<br/>Suite"]
        DestSvc["Destination<br/>Service"]
        TokenSvc["XSUAA / IAS<br/>Token Service"]
    end

    MCPClient -->|MCP Protocol| Transport
    HTTP -->|Direct| S4
    HTTP -->|Via BTP| BTPSuite
    BTPSuite --> S4
    HTTP --> IDoc
    Auth -->|Token Exchange| DestSvc
    Auth -->|OIDC / OAuth2| TokenSvc
    DestSvc --> S4

    style n8n fill:#e8f4fd,stroke:#4a90d9
    style Server fill:#f5f5f5,stroke:#555
    style SAP fill:#e8f0fe,stroke:#1a6fb5

Integration Paths

graph LR
    subgraph Path1["Path 1: Direct"]
        n1["n8n"] -->|MCP| s1["MCP Server"] -->|Basic Auth| sap1["SAP S/4HANA"]
    end

    subgraph Path2["Path 2: BTP Client Credentials"]
        n2["n8n"] -->|MCP| s2["MCP Server"] -->|OAuth2| btp2["BTP Suite"] --> sap2["SAP S/4HANA"]
        s2 -->|CC Flow| tok2["XSUAA"]
    end

    subgraph Path3["Path 3: BTP Principal Propagation"]
        n3["n8n + JWT"] -->|MCP| s3["MCP Server"] -->|JWT Exchange| dest3["Destination Svc"] --> sap3["SAP S/4HANA"]
    end

    subgraph Path4["Path 4: SAML Bearer (no BTP)"]
        n4["n8n + JWT"] -->|MCP| s4["MCP Server"] -->|"SAML Assertion<br/>RSA-SHA256"| sap4["SAP OAuth2<br/>Endpoint"]
    end

    style Path1 fill:#e8f4fd,stroke:#4a90d9
    style Path2 fill:#fef9e7,stroke:#e8a317
    style Path3 fill:#eafaf1,stroke:#5b8c5a
    style Path4 fill:#fdf2e9,stroke:#8b5e3c

Request Flow (OData Write)

sequenceDiagram
    participant LLM as LLM (via n8n)
    participant Tool as MCP Tool
    participant Registry as ToolRegistry
    participant OData as ODataClient
    participant HTTP as SapHttpClient
    participant SAP as SAP Gateway

    LLM->>Tool: sap_create(serviceUrl, entitySet, data)
    Tool->>Registry: isToolVisible?
    Registry-->>Tool: yes
    Tool->>OData: create(entitySet, data)
    OData->>HTTP: request(POST, url, data)

    Note over HTTP,SAP: CSRF Token Fetch
    HTTP->>SAP: GET /sap/opu/odata/sap/SRV/<br/>x-csrf-token: fetch<br/>sap-client: 324
    SAP-->>HTTP: x-csrf-token: TOKEN<br/>set-cookie: SESSION

    Note over HTTP,SAP: Mutating Request
    HTTP->>SAP: POST /sap/opu/odata/sap/SRV/EntitySet<br/>x-csrf-token: TOKEN<br/>Cookie: SESSION
    SAP-->>HTTP: 201 Created + entity data

    HTTP-->>OData: response
    OData-->>Tool: created entity
    Tool-->>LLM: JSON result via MCP

Supported SAP Systems

The MCP server supports the following SAP backends. Connector availability depends on the target system; see footnotes for prerequisites.

| Connector | ECC 6.0+ (EHP 7+) | S/4HANA on-prem | S/4HANA Cloud (Public) | |-----------------------|---------------------------|------------------------|------------------------| | OData V2 | ✅ supported [^1] | ✅ supported | ✅ supported | | OData V4 | ⚠️ partial [^4] | ✅ supported | ✅ supported | | IDoc (HTTP/XML) | ✅ supported [^1] | ✅ supported | ❌ N/A [^3] | | RFC/BAPI | ✅ supported [^1][^2][^5] | ✅ supported [^2][^5] | ❌ N/A [^3] |

Additionally validated against:

SAP BTP Integration Suite (as intermediary for S/4HANA Cloud RFC/IDoc paths)
SAP API Business Hub Sandbox

[^1]: NetWeaver Gateway ICF services must be activated (transaction SICF). See Setup for SAP ECC. [^2]: Requires SAP NW RFC SDK 7.50+ on the host. node-rfc is declared as optionalDependencies; missing SDK degrades gracefully with a startup warning. [^3]: S/4HANA Cloud Public Edition does not expose RFC or classic IDoc-HTTP for external consumers. Use SAP BTP Integration Suite as an intermediary. [^4]: OData V4 in ECC is rare; most ECC NetWeaver Gateway services are V2. V4 is the default for S/4HANA. [^5]: SNC library (SAP_SNC_LIB) is OS-specific (.so / .dylib / .dll) and must be installed separately.

Documentation

Setup Guide -- Installation, all 7 auth types, CLI flags, Docker deployment
Architecture -- Technical architecture, request flows, design decisions
API Reference -- All 17 tools, resources, and prompts with parameters
Examples -- SAP workflow examples with step-by-step instructions

Technology

Built with:

MCP TypeScript SDK v1.x
axios -- HTTP client with CSRF + redirect handling
jose -- JWT/JWKS validation for IAS/XSUAA auth
fast-xml-parser -- IDoc XML + SAML assertion building
Zod v4 -- Schema validation
pino -- Structured JSON logging
tsup -- ESM bundling
TypeScript 5.9, Node.js >= 22.18.0

SAP, S/4HANA, ECC, NetWeaver, ABAP are trademarks or registered trademarks of SAP SE in Germany and other countries. This project is not affiliated with SAP SE.

License

ISC