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

"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

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/API_BUSINESS_PARTNER, Entity Set A_BusinessPartner
• Query Options → Filter Country eq 'DE', Select BusinessPartner,BusinessPartnerName, Top 100

Create a sales order with items (deep insert):

• Resource OData, Operation Create, Service URL /sap/opu/odata/sap/API_SALES_ORDER_SRV, Entity Set A_SalesOrder
• Data:

{
  "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:

• Resource OData, Operation Upload Media
• Service URL /sap/opu/odata/sap/API_CV_ATTACHMENT_SRV, Entity Set AttachmentContentSet
• Input Binary Field data — file name and content type come from the binary metadata; Upload Options overrides either
• Object Headers:

{
  "BusinessObjectTypeName": "BUS2032",
  "LinkedSAPObjectKey": "{{ $json.salesOrder.padStart(10, '0') }}",
  "DocumentInfoRecordDocType": "PDF"
}

Three things decide whether this works:

• The object key goes out ten digits wide with leading zeros. Sales order 4711 is 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.
• Object Headers is a JSON field, not a pair list, because empty values must be omitted entirely. A header sent empty makes SAP answer with the same misleading message. Leave a line out instead of setting it to "".

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:
SAP_MCP_URL=http://localhost:8808 SAP_MCP_TOKEN=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.0 && git push origin 0.3.0

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

• GuniWeb SAP MCP Server — documentation, releases, issues
• Server tool reference (all parameters and responses)
• Which SAP interfaces the server uses, and how it behaves
• n8n community nodes documentation

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

• 0.3.0 — optional Trace Parent parameter: a W3C 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.
• 0.2.0 — binary payloads: Upload Media and Download Media for SAP media entities (attachments, document images). Needs GuniWeb SAP MCP Server 0.5.0 or newer. Until now an attachment had to go around the node through an HTTP Request node, which meant rebuilding the certificate chain, the CSRF handshake, the client parameter and the error handling by hand.
• 0.1.0 — first release: OData (query/read/create/update/delete/function/batch), Discovery, IDoc, generic Tool resource; credential with connection test and optional personal SAP login (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.