Description
n8n-nodes-guniweb-sap
SAP S/4HANA and SAP ECC as deterministic workflow steps in n8n — query, read, create, update and delete OData entities (V2 and V4), call function imports and actions, run $batch requests, and send or track IDocs over HTTP/XML — no RFC SDK, no middleware, no AI agent required.
The node is a thin, dependency-free client for the GuniWeb SAP MCP Server (npm i -g guniweb-sap-mcp, free to use). The server holds the SAP connections and credentials; n8n holds only an access token. One server can serve several SAP systems and several n8n workflows, each with its own token and permissions (read-only, tool tiers).
Why a node when n8n already has an MCP Client? The MCP Client node lives inside AI Agents. This node makes the same SAP operations available as regular nodes — the workflow author decides which operation runs with which parameters, results arrive as items, and there is no LLM in the loop unless you attach the node to an agent as a tool (it is usableAsTool). That is the setup we recommend for SAP: AI-assisted, human-governed workflows.
Installation · Prerequisites · Credentials · Operations · Usage · Compatibility · Resources · Support · Version history
Installation
Follow the installation guide in the n8n community nodes documentation. Package name: n8n-nodes-guniweb-sap.
Prerequisites
A running GuniWeb SAP MCP Server in HTTP mode, reachable from n8n — typically as a container next to n8n:
npx guniweb-sap-mcp --transport http --port 8808 --destinations /config/destinations.json
issue a token for the SAP system the workflows should use:
guniweb-sap-mcp tokens issue s4prod --label "n8n prod" [--read-only] [--tiers core,odata]
The token is printed once; put it into the n8n credential (below). Server setup, destinations.json, tokens and the optional Admin API are documented in the server’s setup guide. Write operations (create/update/delete/function/batch/IDoc send) additionally require the server to run with --allow-write and a token that is not read-only; IDoc operations require the idoc tier.
Credentials
GuniWeb SAP MCP Server API
| Field | Meaning |
|—|—|
| Server URL | Base URL of the server, e.g. http://sap-mcp:8808 inside Docker or https://sap-mcp.example.com. /mcp is added automatically. |
| Access Token | The Bearer token issued on the server (tokens issue or POST /admin/tokens). It authenticates the request and selects the SAP system. |
| SAP User / SAP Password | Personal SAP login — only for destinations the server runs with authType: "user-basic": your own SAP credentials travel with every call and are used for that call only; SAP authorizations and change documents are on you. Leave empty when the destination uses a technical SAP user. |
| Request Timeout | Per call, default 120 s — keep it above the server’s tool timeout (default 30 s). |
“Test credential” performs a tools/list round trip: 200 = URL and token are right (and, for user-basic, the SAP login was sent), 401 = token rejected or SAP login missing, connection error = URL or transport wrong. Whether SAP accepts the personal login is what Discovery → Test Connection tells you.
Two ways to act in SAP. With a technical user (destination authType: "basic", oauth2, …) the server holds the SAP credentials and every workflow acts as that user. With the personal login (user-basic) every person acts as themselves — the recommended setup when several people build workflows against one system. German step-by-step guides: für Anwender · für Administratoren.
Operations
| Resource | Operation | Server tool | Notes |
|—|—|—|—|
| OData | Query | sap_query | $filter, $select, $expand, $orderby, $top, $skip; one item per row by default |
| | Read | sap_read | one entity by key (JSON object) |
| | Create | sap_create | deep insert via nested navigation properties |
| | Update | sap_update | ETag/CSRF handled by the server |
| | Delete | sap_delete | |
| | Call Function | sap_function | V2 function imports, V4 actions/functions (bound and unbound) |
| | Batch | sap_batch | several operations in one $batch |
| | Upload Media | sapmediaupload | a binary field as raw bytes into a media entity (attachment, document image) — file name as Slug, object headers as JSON |
| | Download Media | sapmediadownload | the raw bytes of a media entity into a binary field |
| Discovery | Test Connection | test-connection | DNS → TLS → auth → client → catalog; a failed stage is returned as data, not thrown |
| | Discover Services | sapdiscoverservices | search + business category, one item per service |
| | List Entity Sets | saplistservices | one item per entity set |
| | Get Metadata | sapgetmetadata | entity types, keys, properties, navigations |
| IDoc | Send | sapidocsend | segments as JSON, control record built by the server |
| | Get Status | sapidocstatus | |
| | Discover Types | sapidocdiscover | |
| | List Received | sapidoclist_received | IDocs SAP posted to the server’s /idoc webhook |
| Tool | List Tools | tools/list | what this token may use, with input schemas |
| | Call Tool | tools/call | any tool by name with raw JSON arguments — the escape hatch for RFC/BAPI, NL query and future tools |
Errors from SAP arrive as node errors with the server’s message, hint and next step; with Continue On Fail they become { error } items.
Usage
Read business partners from Germany, one item each:
- Resource OData, Operation Query
- Service URL
/sap/opu/odata/sap/APIBUSINESSPARTNER, Entity SetA_BusinessPartner - Query Options → Filter
Country eq 'DE', SelectBusinessPartner,BusinessPartnerName, Top100 - Resource OData, Operation Create, Service URL
/sap/opu/odata/sap/APISALESORDERSRV, Entity SetASalesOrder - Data:
Create a sales order with items (deep insert):
{
"SalesOrderType": "OR",
"SalesOrganization": "1010",
"DistributionChannel": "10",
"OrganizationDivision": "00",
"SoldToParty": "{{ $json.customer }}",
"to_Item": [
{ "Material": "{{ $json.material }}", "RequestedQuantity": "{{ $json.qty }}" }
]
}
Requires the server to run with --allow-write and a token without readOnly. Before automating document creation, settle the two questions the server documentation raises (write governance and SAP Digital Access) with your SAP team.
Attach a PDF to a sales order:
/sap/opu/odata/sap/APICVATTACHMENT_SRV, Entity Set AttachmentContentSetdata — file name and content type come from the binary metadata; Upload Options overrides either{
"BusinessObjectTypeName": "BUS2032",
"LinkedSAPObjectKey": "{{ $json.salesOrder.padStart(10, '0') }}",
"DocumentInfoRecordDocType": "PDF"
}
Three things decide whether this works:
0000004711.BusinessObjectTypeName must match the object. A sales order is BUS2032. Get either wrong and SAP answers “User has no authorization for operation 03 on object …”, which is not about authorisations — the server’s error message names both causes."".There is no PATCH on this service: uploading again does not replace the first file, it attaches a second document to the same object. Verify with Call Function → GetAllOriginals before repeating an upload — that is a reading function import and works on a read-only connection too.
The file travels base64-encoded inside the JSON-RPC request, so the server’s request limit applies (16 MB of body, roughly a 12 MB file; --max-request-bytes raises it).
Follow a job across systems (W3C Trace Context):
Set Trace Parent to the traceparent your calling application created for the job, e.g. {{ $json.traceparent }}. The node sends it as a traceparent header, and the server writes its trace ID into the log line of every tool call, next to its own correlation ID. One grep on the trace ID then leads from the calling application to the SAP request. The value is only logged. The server checks the format and ignores an invalid value, so a typo never breaks a workflow. Leave the field empty if you do not trace.
Anything else: Resource Tool → List Tools shows what the server exposes for your token, Call Tool runs it with raw JSON arguments.
Development
npm install
npm run lint && npm test && npm run build
smoke run against a real server:
SAPMCPURL=http://localhost:8808 SAPMCPTOKEN=gsm_… node scripts/smoke-real-server.mjs
Releasing
Set the version in package.json, add the changelog entry, then push a tag without a v
prefix — that is what the publish workflow listens for, and it publishes to npm with provenance:
git tag 0.3.1 && git push origin 0.3.1
npm run release (the interactive n8n-node release) does not work here: the CLI invokes
release-it with -n, an option release-it 21 no longer knows. We stay on release-it 21 because
release-it 20 pulls in an undici with a TLS certificate validation bypass, and the release path
that matters — the workflow — never touches release-it: inside CI the CLI runs lint, build and
npm publish directly.
Compatibility
Built and linted with @n8n/node-cli against n8n 2.x (n8n-workflow peer dependency, n8nNodesApiVersion: 1). Requires GuniWeb SAP MCP Server ≥ 0.3.0 in HTTP transport (--transport http), ≥ 0.4.0 for the personal SAP login (user-basic), ≥ 0.7.0 for the trace ID in the server log (older servers ignore the header); the legacy SSE transport is not supported. No runtime dependencies.
Resources
Support
Community: issues in this repository (node) or in the server repository (SAP behaviour). Commercial support, production SLAs and implementation: guniweb.de/sap-mcp · support@guniweb.de.
Version history
429 from the server’s rate limit (server 0.9.0 or newer, reason: "call-rate-limit") now names the limit that was reached (token or SAP destination), with the server’s hint and the wait from Retry-After. Until now every 429 read as “too many failed authentications”.traceparent sent as HTTP header to /mcp, so the server (0.7.0 or newer) writes the trace ID next to its correlationId. A job can then be followed from the calling application through n8n to the SAP request. Older servers ignore the header.user-basic destinations).License
MIT — see LICENSE.md. SAP and S/4HANA are trademarks of SAP SE; this project is not affiliated with SAP SE.
