Repository avatar
Other Tools
v0.1.0
active

sap-b1-mcp

io.github.kodenova/sap-b1-mcp

Read-only SAP Business One Service Layer tools: partners, items, orders, invoices, stock.

Documentation

sap-b1-mcp: read-only SAP Business One MCP server

An open-source Model Context Protocol server that lets AI assistants (Claude, ChatGPT via a bridge, Cursor, VS Code and other MCP clients) read data from one SAP Business One company through the Service Layer REST API.

It is a deliberately small, auditable starter:

  • Read-only by design. There are no tools that create, change or delete anything, and the HTTP client refuses any request other than GET, Login, Logout and running a pre-created SQLQueries entry.
  • No free SQL and no free filters. Every tool has a typed input schema, a row limit and a field whitelist. Custom reports go through run_saved_query, which only runs queries an administrator registered in a config file.
  • Credentials stay private. They come from environment variables, are never logged, and are redacted from every error message.
  • Runs without SAP. SAPB1_MOCK=1 serves bundled demo fixtures, so you can try it and run the tests on any machine.

SAP and SAP Business One are trademarks or registered trademarks of SAP SE in Germany and other countries. This project is independent and is not affiliated with, sponsored by or endorsed by SAP SE.

Tools

ToolWhat it returnsKey inputsRow limit
get_business_partnerOne customer, supplier or lead by exact CardCodecardCode, optional fields1
search_business_partnersPartners whose code or name contains textquery, type (customer / supplier / lead), limit, fieldslimit (≤ SAPB1_MAX_ROWS)
get_itemOne item master record by exact ItemCodeitemCode, optional fields1
search_itemsItems whose code or name contains textquery, inStockOnly, limit, fieldslimit
get_open_sales_ordersOpen sales orders, newest firstoptional cardCode, limit, fieldslimit
get_customer_balanceAccount balance, open orders, open deliveries, credit limit and available creditcardCode1
get_open_invoicesOpen A/R invoices with unpaid amount and days overdue, plus a totaloptional cardCode, overdueOnly, limitlimit
get_stock_by_warehouseIn stock, committed, ordered and available per warehouse for one itemitemCode, optional warehouseCode, includeEmptyall warehouses of one item
run_saved_queryResult of a query pre-registered by an administratorname, params, limitmin(limit, query maxRows)

Every tool is annotated readOnlyHint: true, destructiveHint: false.

Field whitelists

The fields input only accepts names from these lists, so the model cannot pull other columns:

  • Business partners: CardCode, CardName, CardType, GroupCode, Phone1, EmailAddress, City, Country, Currency, FederalTaxID, Valid, Frozen
  • Balance: CardCode, CardName, Currency, CurrentAccountBalance, OpenOrdersBalance, OpenDeliveryNotesBalance, CreditLimit
  • Items: ItemCode, ItemName, ItemsGroupCode, BarCode, InventoryItem, SalesItem, PurchaseItem, InventoryUOM, QuantityOnStock, QuantityOrderedFromVendors, QuantityOrderedByCustomers, Valid, Frozen
  • Documents (orders, invoices): DocEntry, DocNum, CardCode, CardName, NumAtCard, DocDate, DocDueDate, DocTotal, DocCurrency, PaidToDate, DocumentStatus

Edit the lists in src/server.ts to fit your company.

Quick start (no SAP needed)

npx -y @kodenova/sap-b1-mcp        # with SAPB1_MOCK=1 in the environment

Or from source:

git clone https://github.com/kodenova/sap-b1-mcp.git
cd sap-b1-mcp
npm install
npm run build
npm test                           # runs in mock mode, no SAP needed
SAPB1_MOCK=1 node dist/index.js    # stdio MCP server on demo data

Requires Node.js 18.17 or later.

Environment variables

VariableRequiredDescription
SAPB1_SERVICE_LAYER_URLyesService Layer base URL, e.g. https://b1server:50000/b1s/v1
SAPB1_COMPANY_DByesCompany database / schema name
SAPB1_USERNAMEyesDedicated read-only B1 user (see Security)
SAPB1_PASSWORDyesPassword of that user. Never logged, redacted from errors
SAPB1_ALLOW_SELF_SIGNEDnotrue to accept a self-signed TLS certificate. Off by default
SAPB1_ALLOW_HTTPnotrue to allow a plain http:// URL. Only for a local test system
SAPB1_MAX_ROWSnoMaximum rows any tool may return. Default 50, hard cap 500
SAPB1_TIMEOUT_MSnoPer-request timeout. Default 30000
SAPB1_SAVED_QUERIES_FILEnoPath to your saved-queries JSON (see below)
SAPB1_LOG_LEVELnodebug, info (default), warn, error, silent. Logs go to stderr
SAPB1_MOCKnotrue / 1 to use the bundled fixtures instead of SAP

See .env.example.

Client setup

Claude Desktop

Edit claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "sap-b1": {
      "command": "npx",
      "args": ["-y", "@kodenova/sap-b1-mcp"],
      "env": {
        "SAPB1_SERVICE_LAYER_URL": "https://b1server:50000/b1s/v1",
        "SAPB1_COMPANY_DB": "SBODEMOUS",
        "SAPB1_USERNAME": "mcp_readonly",
        "SAPB1_PASSWORD": "your-password",
        "SAPB1_MAX_ROWS": "50"
      }
    }
  }
}

To try it without SAP, replace the env block with { "SAPB1_MOCK": "1" }. On Windows, if npx is not found, use "command": "cmd" and "args": ["/c", "npx", "-y", "@kodenova/sap-b1-mcp"].

Claude Code

claude mcp add sap-b1 \
  -e SAPB1_SERVICE_LAYER_URL=https://b1server:50000/b1s/v1 \
  -e SAPB1_COMPANY_DB=SBODEMOUS \
  -e SAPB1_USERNAME=mcp_readonly \
  -e SAPB1_PASSWORD=your-password \
  -- npx -y @kodenova/sap-b1-mcp

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json, with the password prompted instead of stored:

{
  "inputs": [
    { "type": "promptString", "id": "sapb1-password", "description": "SAP B1 password", "password": true }
  ],
  "servers": {
    "sap-b1": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kodenova/sap-b1-mcp"],
      "env": {
        "SAPB1_SERVICE_LAYER_URL": "https://b1server:50000/b1s/v1",
        "SAPB1_COMPANY_DB": "SBODEMOUS",
        "SAPB1_USERNAME": "mcp_readonly",
        "SAPB1_PASSWORD": "${input:sapb1-password}"
      }
    }
  }
}

Cursor, Windsurf and other stdio clients

Use the same command, args and env as the Claude Desktop example in the client's MCP config file (for Cursor: ~/.cursor/mcp.json or .cursor/mcp.json).

ChatGPT and other remote-only clients

ChatGPT connects to remote MCP servers over HTTPS; it does not launch local stdio processes. This package is a stdio server, so for ChatGPT you need to host it behind an MCP stdio-to-HTTP bridge on a server you control, with HTTPS and authentication in front of it. Do not expose an unauthenticated endpoint that holds your SAP credentials. If you want a hosted, authenticated HTTP version, see the footer.

Saved queries (run_saved_query)

The model cannot send SQL or OData filters. It can only pick a query by name from a JSON file you control and pass the typed parameters that query declares. Copy config/saved-queries.example.json to config/saved-queries.json and point SAPB1_SAVED_QUERIES_FILE at it.

Two kinds are supported:

{
  "queries": {
    "customers_over_balance": {
      "kind": "odata",
      "description": "Customers whose account balance is above a threshold",
      "resource": "BusinessPartners",
      "select": ["CardCode", "CardName", "CurrentAccountBalance"],
      "filter": { "and": [
        { "field": "CardType", "op": "eq", "value": "cCustomer" },
        { "field": "CurrentAccountBalance", "op": "gt", "value": { "param": "minBalance" } }
      ]},
      "orderBy": "CurrentAccountBalance desc",
      "maxRows": 100,
      "params": { "minBalance": { "type": "number", "default": 0 } }
    },
    "sales_by_month": {
      "kind": "sqlquery",
      "description": "Net A/R sales per month for a year",
      "sqlCode": "KN_SALES_BY_MONTH",
      "params": { "year": { "type": "integer", "required": true } }
    }
  }
}
  • odata queries run against a Service Layer entity set with a fixed $select and a structured filter. Parameter values are type-checked (string, number, integer, date, boolean) and escaped; field names are validated.
  • sqlquery queries run a SQLQueries entry that your administrator already created in Service Layer (POST SQLQueries('code')/List with a ParamList). Service Layer only accepts SELECT statements there. This server cannot create or change SQLQueries entries.

Security

  • No write path. The client-side guard (assertReadOnly in src/serviceLayer.ts) blocks PATCH, PUT, DELETE and every POST except Login, Logout and SQLQueries('…')/List, before any request is sent. Tests cover this.

  • Use a dedicated least-privilege B1 user. Create a separate user (for example mcp_readonly) for this server. Do not use manager or a superuser. In Administration → System Initialization → Authorizations → General Authorizations, set:

    • Read Only for Business Partner Master Data, Item Master Data, Sales A/R (Orders, A/R Invoices) and Inventory reports you want exposed
    • No Authorization for everything else, including Administration, Banking, Financials and all purchasing or posting screens you do not need

    The server is read-only on its own; the B1 authorizations are your second, independent layer. Service Layer logins need a suitable B1 user license, so check the licensing with your SAP partner.

  • Credentials. Read only from environment variables. Never written to logs. Password, B1SESSION and ROUTEID values are redacted from every error and log line. Prefer your client's secret prompt (as in the VS Code example) over storing the password in a config file.

  • TLS. Certificate verification is on by default. SAPB1_ALLOW_SELF_SIGNED=true turns it off for the Service Layer host only and logs a warning. Plain http:// is refused unless SAPB1_ALLOW_HTTP=true.

  • Bounded output. Every list tool has a row limit (default 20, max SAPB1_MAX_ROWS, hard cap 500) and a field whitelist, so a prompt cannot dump whole tables.

  • Prompt injection. Data returned from SAP (names, remarks) is passed to the model as data. Because the tools cannot write, a malicious record cannot make the model change your ERP through this server. Still, review what other tools you connect alongside it.

  • Logs go to stderr, never stdout (stdout is the MCP protocol channel).

Service Layer version notes

  • Built for the Service Layer v1 endpoint (/b1s/v1), which uses OData v3-style JSON (odata.nextLink, {"error":{"message":{"value":…}}}). The client also reads the v2 (/b1s/v2, OData v4) @odata.nextLink and error format, but filters with dates are written in v1 syntax, so v1 is the supported endpoint for 0.1.0.
  • Paging: Service Layer returns 20 rows per page by default. The server sends Prefer: odata.maxpagesize=N and follows odata.nextLink until the row limit is reached.
  • Sessions: login is POST /Login with CompanyDB, UserName and Password; the B1SESSION (and ROUTEID when load-balanced) cookies are reused. When the session times out (30 minutes by default), the server logs in again once and retries. It logs out on shutdown.
  • contains() and startswith() are used for search. On SAP HANA, string comparison is case-sensitive, so search_items with widget will not match Widget.
  • SQLQueries (used by sqlquery saved queries) exists only in newer Service Layer releases. Check that SQLQueries appears in your $metadata before using that kind.
  • Field names follow the standard Service Layer metadata (BusinessPartners, Items, Orders, Invoices). If your release or localization differs, adjust the whitelists in src/server.ts.

Limitations

  • Read-only. No document creation, approvals, payments or master-data changes.
  • One company database per server process. Run several processes for several companies.
  • Service Layer only. The DI API (COM) and direct database access are not used.
  • No user-defined fields (UDFs) in the default whitelists. Add U_… fields yourself if needed.
  • Search uses contains(), which can be slow on very large tables without suitable indexes; keep limits small.
  • stdio transport only in this release. Remote clients such as ChatGPT need a bridge you host and secure.
  • Tested with unit tests, the bundled fixtures and a fake Service Layer HTTP server. Validate against a test company before you point it at production.

Development

npm install
npm run build
npm test

Project layout:

src/index.ts         stdio entry point (bin)
src/server.ts        the 9 MCP tools, schemas, whitelists
src/serviceLayer.ts  Service Layer client: login, cookies, paging, read-only guard
src/mock.ts          fixture-backed data source for SAPB1_MOCK=1
src/savedQueries.ts  saved-query config loader and parameter binding
src/odata.ts         structured filter → OData, escaping
src/redact.ts        credential redaction
fixtures/            demo data (fictional)
config/              saved-queries example
test/                vitest suites (mock mode + fake Service Layer)

Contributions are welcome. Please keep the server read-only: pull requests that add write endpoints will not be merged into this package.

License

MIT © 2026 Kodenova / Zain Abbas. See LICENSE.

SAP and SAP Business One are trademarks or registered trademarks of SAP SE in Germany and other countries. This project is not affiliated with, sponsored by or endorsed by SAP SE. All demo data in fixtures/ is fictional.


Built by Kodenova, an independent SAP Business One development studio that works alongside your SAP partner. Need write access, custom tools or DI API? kodenova.com/services/mcp-server-development/

NPM
@kodenova/sap-b1-mcp
Install Command
npm install @kodenova/sap-b1-mcp
Runtime: npx