SAP B1 ServiceLayer MCP Server

MCP (Model Context Protocol) server to connect AI assistants (opencode, Claude, etc.) to the SAP Business One 10.0 ServiceLayer, on a local network. Runnable with npx from this GitHub repository, without installing anything on the PC.

Features

• Read-only by default: with SAP_B1_READONLY=true (default) only query tools (GET) are registered. Write tools (POST/PATCH/DELETE) do not exist on the server and cannot be called.

• Full discovery: sap_list_entities, sap_get_entity_schema and sap_list_actions query GET /$metadata (downloaded once per process and cached) and expose the ~140 CRUD entities (including user tables @ and UDOs) and the hundreds of ServiceLayer service methods.

• Optional write mode: with SAP_B1_READONLY=false, sap_create, sap_update, sap_delete are enabled for ServiceLayer entities and sap_call_action for service methods (which may have side effects).

• Run via npx github:: no manual installation.

• Managed session: implicit login with CompanyDB/username/password, B1SESSION + ROUTEID cookies kept in memory (supports multi-node ServiceLayer), automatic re-login on 401, and guaranteed logout when the process exits (in addition to the sap_logout tool).

• Self-signed TLS: support for self-signed ServiceLayer certificates (typical in local environments) via SAP_B1_VERIFY_TLS=false.

• No telemetry or external calls: the HTTP client points exclusively to the configured URL (SAP_B1_SERVER_URL).

• Security limits: top capped at 200 records per query.

Related MCP server: BTP MCP Server

Tools

Read (always available)

Write (only if SAP_B1_READONLY=false)

Requirements

• Node.js 18+

• SAP Business One 10.0 with ServiceLayer enabled (typical path https://<host>:50000/b1s/v1)

• opencode (or any MCP client)

Configuration (environment variables)

Usage with opencode

In the project's opencode.json:

{
  "mcp": {
    "sap-b1-servicelayer": {
      "type": "local",
      "command": ["npx", "-y", "github:leonardows1/sap-b1-servicelayer-mcp"],
      "environment": {
        "SAP_B1_SERVER_URL": "https://<host>:50000/b1s/v1",
        "SAP_B1_DATABASE": "<CompanyDB>",
        "SAP_B1_USERNAME": "<usuario>",
        "SAP_B1_PASSWORD": "<password>",
        "SAP_B1_SESSION_TIMEOUT": "30",
        "SAP_B1_VERIFY_TLS": "false",
        "SAP_B1_READONLY": "true"
      },
      "enabled": true
    }
  }
}

Restart opencode after saving the configuration.

Security

• Credentials and session cookies are never logged.

• The process only communicates with SAP_B1_SERVER_URL.

• In READONLY=true mode the write tools are not registered: it is impossible to create/update/delete records, by design.

• Configuration validated at startup: missing SAP_B1_SERVER_URL, SAP_B1_DATABASE, SAP_B1_USERNAME or SAP_B1_PASSWORD → the process aborts with a clear message.

• Entity names validated (^[A-Za-z][A-Za-z0-9_]*$): routes cannot be injected (e.g. BusinessPartners/...).

• Key values and filters escaped in OData (single quotes doubled): an id or ItemCode with ' does not break the URL or the $filter.

• The password is stored in plain text in the MCP client configuration. Consider a secret manager if the repository is shared.

• npx github: has no semver versioning: each run takes the latest version of the main branch. After updating the repo, use npm cache clean --force to force a reload.

Structure

Pragmatic hexagonal architecture (ESM, no framework): the domain and use cases do not know about the MCP transport or HTTP; the infrastructure implements the ServiceLayerPort port (DIP) and the MCP tools are thin controllers.

sap-b1-servicelayer-mcp/
├── package.json                  # Definición del paquete npm (bin: server.js)
├── server.js                     # Composition root: cablea dependencias y arranca stdio
├── src/
│   ├── config/
│   │   └── config.js             # Configuración desde env, validada e inmutable
│   ├── domain/
│   │   ├── errors.js             # Excepciones tipadas (Configuration/InvalidArgument/ServiceLayer)
│   │   ├── oData.js              # Helpers puros: query string, filtros, clamp de $top, validación de entidad
│   │   └── edmx.js               # Parseo puro de $metadata: entity sets, esquemas, function imports
│   ├── application/
│   │   ├── ports.js              # Puerto ServiceLayerPort (contrato, DIP)
│   │   ├── helpers.js            # ensureOk / ensureSuccess / unwrapValue
│   │   └── services/
│   │       ├── queryService.js   # Consulta GET genérica a entidades OData
│   │       ├── catalogService.js # Socios de negocio y artículos (compone QueryService)
│   │       ├── salesService.js   # Pedidos de venta y stock
│   │       ├── sessionService.js # Estado y cierre de sesión
│   │       ├── writeService.js   # create / update / delete
│   │       ├── metadataService.js # Descubrimiento: $metadata cacheado, entidades, esquemas y actions
│   │       └── sqlService.js     # SQL de solo lectura (SELECT/WITH) vía POST /sql_query
│   └── infrastructure/
│       ├── http/
│       │   ├── httpClient.js     # Cliente HTTP mínimo (http/https)
│       │   ├── cookies.js        # Manipulación pura de cookies de sesión
│       │   └── serviceLayerClient.js # Adaptador del puerto: login, 401, logout
│       └── mcp/
│           ├── result.js         # ok / err / serialize / handle (controladores delgados)
│           └── tools.js          # Registro de tools MCP
├── test/                         # node:test (sin dependencias externas)
│   ├── config.test.js
│   ├── oData.test.js
│   ├── edmx.test.js              # parseo EDMX v3/v4 (entity sets, esquemas, function imports)
│   ├── cookies.test.js
│   ├── client.test.js
│   ├── fakePort.js               # fake tipado del puerto ServiceLayerPort (compartido)
│   ├── services.test.js          # casos de uso con cliente fake (anti-inyección)
│   ├── metadataService.test.js   # descubrimiento y acciones con fake
│   ├── sqlService.test.js        # SQL solo-lectura (rechazos, Service Not Found)
│   └── tools.test.js             # integración MCP in-memory (registro y llamadas)
├── .gitignore
└── README.md

Adaptation to the real schema (verified against ServiceLayer 10.0 v1)

The server dynamically adapts to each instance's $metadata, with nothing hardcoded. Facts verified on a real instance (v1, OData v3):

• Entity sets share an EntityType: Orders/Invoices/DeliveryNotes → SAPB1.Document. sap_get_entity_schema resolves the real type automatically.

• Document lines: in v1 they are complex collections (DocumentLines, DocumentInstallments) that come inline in the response; $expand only applies to navigationProperties (the schema lists them, e.g.: BusinessPartner, Currency).

• Financial fields: in v1 BusinessPartners has no Balance; use CurrentAccountBalance, OpenOrdersBalance, OpenDeliveryNotesBalance. Invoices have no BalanceDue: the open balance is DocTotal − PaidToDate.

• No ItemStock or /sql_query on old v1: sap_get_stock warns with real stock entities discovered; sap_sql_query returns a clear error.

• V3 function imports with IsBindable="true" are listed as bound (not invocable standalone) so they do not pollute sap_list_actions.

Recipe: balance aging report (30/60/90)

Without SQL, using only sap_query (works on any v1/v2):

1. Open invoices (paginate with skip in batches ≤200 if there are many):

   sap_query('Invoices',
     filter='PaidToDate lt DocTotal',
     select='CardCode,CardName,DocNum,DocDate,DocDueDate,DocTotal,PaidToDate,DocumentStatus,ControlAccount')

2. For each invoice: balance = DocTotal − PaidToDate; days = today − DocDueDate.

3. Group by ranges 0-30 / 31-60 / 61-90 / 90+ and by customer (or by ControlAccount for the view by G/L account).

4. Totals by customer/account: sap_get_business_partners with CurrentAccountBalance (current balance) and CreditLimit.

With sap_sql_query (v2) the same report is a single query against OINV/OINV3/OFRJ/OCRD.

Development

npm install     # dependencias
npm test        # tests (node:test)
npm run typecheck  # verificación de tipos estricta (tsc --noEmit sobre JSDoc)
npm start       # arranque local (requiere variables de entorno)

All the JS code is verified with strict TypeScript via JSDoc (checkJs + strict + noUncheckedIndexedAccess): tsconfig.json with no build step, the server runs directly with node.

Manual verification (JSON-RPC over stdio)

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  SAP_B1_SERVER_URL=... SAP_B1_DATABASE=... SAP_B1_USERNAME=... SAP_B1_PASSWORD=... \
  npx -y github:leonardows1/sap-b1-servicelayer-mcp