b1-mcp-server for SAP B1

b1-mcp-server

A secure Model Context Protocol server that gives an AI client (e.g. Claude Code) guarded access to SAP Business One via both the database (HANA / MS SQL) and the Service Layer OData API.

Features

• 7 MCP tools: connect_database, execute_sql, execute_service_layer (GET), execute_service_layer_write (PATCH / POST / DELETE), execute_service_layer_write_unattended (the same writes without approval, development profiles only), get_schema_info, check_connection.
• Multi-environment: switch between client databases at runtime via named connection profiles. No restart needed.
• Read-only by design: the SQL path executes only SELECT. Every INSERT/UPDATE/DELETE/DROP/CREATE/ALTER/EXEC is blocked server-side with no confirmation bypass — writes are handed to a human to run in a real DB client.
• Server-side guardrails: all raw SQL submitted to execute_sql goes through the same validation whether the user or the AI wrote it. Anonymous DO BEGIN..END blocks are classified by the most dangerous statement inside them, so a write hidden behind a trailing SELECT is still a write.
• Audit trail: selected-profile connection attempts and database/Service Layer calls that reach policy or execution are recorded as JSON Lines, including policy denials.
• Rate limiting per tool with sliding window.

Install

Requires Node.js 22 or newer.

npx b1-mcp-server

Or add to your Claude Code MCP config:

{

"mcpServers": { "b1-db": { "command": "npx", "args": ["-y", "b1-mcp-server"] } } }

Dependencies

Five runtime dependencies: @modelcontextprotocol/sdk, zod, @sap/hana-client and mssql (plus generic-pool, which backs the HANA connection pool). Database access is a local driver — src/db/directDb.ts — built directly on the HANA and MS SQL clients; Service Layer traffic goes through the strict-TLS adapter in src/sl/serviceLayerAdapter.ts using Node's own fetch and https. No HTTP framework, no axios, no PostgreSQL driver.

The package ships with no overrides block, so npx -y b1-mcp-server installs the same tree a project install does (overrides never applied to npx, which runs without a root package.json). As of 1.6.0, npm audit --omit=dev reports 0 vulnerabilities.

Connection profiles

The server starts unconnected. Connections are loaded from ~/.claude/connections.json (one profile per environment) and selected at runtime by the AI via the connect_database tool.

Profile matching behavior in connect_database:

• Exact match by id or dbName is preferred.
• Partial matches are accepted only when they resolve to a single profile.
• Ambiguous partial matches are rejected with a list of candidates.

Example ~/.claude/connections.json:

[

{ "id": "client_a_prd", "dbType": "hana", "dbServer": "10.0.0.10:30015", "dbName": "SBO_CLIENT_A", "dbUser": "B1ADMIN", "dbPassword": "•••", "slUrl": "https://10.0.0.10:50000/b1s/v2", "slUser": "manager", "slPassword": "•••", "slAllowedMethods": ["GET", "PATCH", "POST"] }, { "id": "client_b_hmg", "dbType": "mssql", "dbServer": "10.0.0.20:1433", "dbName": "SBO_CLIENT_B_HMG", "dbUser": "SA", "dbPassword": "•••" } ]

Every profile requires id, dbType and dbName. Add dbServer and dbUser to configure DirectDb; add slUrl and slUser to configure Service Layer. Each configured side also requires its non-empty password (dbPassword or slPassword). Missing/empty passwords fail locally without a login attempt, avoiding an unnecessary failure that may count toward account lockout under the configured login policy. Non-empty password strings are passed through without trimming. Either side, or both sides, can be configured in one profile.

slAllowedMethods (optional) lists the HTTP verbs the Service Layer tools may send for that profile: any of GET, PATCH, POST, DELETE (case-insensitive). Without it a profile is read-only (["GET"]); every write verb must be listed explicitly. PUT is not supported, because it replaces the whole entity and wipes every field the body omits. An invalid value (unknown verb, empty list, not an array) skips that profile instead of guessing. The list is applied on connect and printed by connect_database; editing it re-logs the Service Layer on the next connect_database call. Allowing a write verb does not waive approval: every write still needs the per-call human acceptance described under the security posture.

slWriteApproval (optional) chooses who approves a write. "elicitation" (default): the server asks through an MCP approval form. "client": the server sends no form and relies on the MCP client's own permission prompt — for setups where the form cannot reach the user, such as Claude Code Remote Control, which forwards permission prompts but not MCP forms. client is honoured only when the MCP client identifies itself as Claude Code; any other client falls back to elicitation. The server cannot see that prompt, so the mode is only as strong as the client's permission settings: list mcp__ __execute_service_layer_write under permissions.ask, never allow, and do not use it with --dangerously-skip-permissions. Without that rule, answering the first prompt with "Yes, don't ask again" saves an allow rule and every later write runs unprompted. Keep production profiles on elicitation. connect_database prints the mode that applies to the current client; editing it re-logs the Service Layer.

"none" is for development companies where a prompt on every write slows the work down. execute_service_layer_write behaves as in client mode, and the profile also unlocks execute_service_layer_write_unattended, which runs the same writes with no approval at all, for any MCP client. That tool refuses every profile not set to "none", so you can list mcp__ __execute_service_layer_write_unattended under permissions.allow and keep the normal write tool under permissions.ask: development profiles run unprompted and every other profile still prompts. The opt-in lives only in the connections file, so it is only as safe as that file: never set "none" on a profile that points at production data.

Both SAP Service Layer roots are supported: /b1s/v1 for OData v3 and /b1s/v2 for OData v4. Login, health checks and relative Service Layer requests use the exact root configured by the profile. Request validation is version-neutral; callers pass only the relative endpoint (for example, Items?$select=ItemCode&$top=1). OData query and payload differences remain the caller's responsibility; configure the root supported by the target SAP B1 installation. SAP deprecated OData v3 starting with SAP Business One 10.0 FP 2405 and made OData v4 the primary protocol, so prefer /b1s/v2 when the target installation supports it; see the Service Layer API reference.

Encrypted credentials (optional, recommended)

The profiles can be stored encrypted in ~/.claude/connections.enc.json instead of the plain-text file (same profile array, AES-256-GCM, key derived from a passphrase with scrypt). Manage it with the creds subcommand of the same binary. Every command reads the passphrase and the passwords only from an interactive terminal: never from an argument, environment variable or pipe, so they stay out of shell history and out of anything an AI tool call can type.

b1-mcp creds migrate      # encrypt the existing plain-text file (once)

b1-mcp creds init # or start an empty encrypted file b1-mcp creds add # add a profile b1-mcp creds edit # Enter keeps a value, "-" clears it b1-mcp creds remove b1-mcp creds list # ids and capabilities, never passwords b1-mcp creds passwd # change the passphrase b1-mcp creds unlock # unlock every running server

With npx, the same commands are npx b1-mcp-server creds … (for example npx b1-mcp-server creds edit client_a_prd). From a clone, run node /path/to/dist/index.js creds …. The is the first column of creds list (or of connect_database with "list"). The locked server prints the exact unlock command for its own install.

• With an encrypted file the server starts locked: connect_database answers with the unlock command and nothing else. Run creds unlock in your own terminal. It sends the passphrase over a Unix socket in a private directory ($XDG_RUNTIME_DIR/b1-mcp/, or ~/.claude/run/; mode 0700, socket 0600). The server keeps only the derived key in memory, closes the socket, and stops accepting attempts after 5 wrong passphrases until it restarts. One unlock reaches every running server (Claude Code, Codex…).
• The passphrase is never asked for through the MCP client.
• add / edit / remove take effect on the next connect_database without a new unlock. After passwd, running servers lock again on their next read.
• migrate does not delete the plain-text file. Change the database and Service Layer passwords afterwards (old copies may survive in backups and sync folders), then delete it. While both files exist the server refuses the plain-text one.
• Plain text stays supported, with a warning in the logs and in connect_database output.
• Native Windows: encrypted credentials are not supported yet (no private Unix socket); use the plain-text file there, or run under WSL.
• Forgotten passphrase = recreate the profiles; there is no recovery.

What it protects: copies of the file (stolen disk, backups, cloud sync, malware that copies files, the Windows side reading a WSL disk). What it does not: code running as your own OS user, which can replace the server or read its memory; a keylogger. An AI agent with shell access runs as your OS user, so encryption alone does not keep the credentials from it. With npx this holds in full: the package is unpacked into your npm cache, which your user (and the agent) can modify.

Separate OS user (strong boundary, manual setup)

The boundary against same-user code is a dedicated OS user that owns the credentials. It cannot be set up through npx; on Linux, roughly:

• Create a system user (e.g. b1mcp) with a private home. The connection files, audit log, trust store and unlock socket follow that user's home.
• Install the package root-owned (e.g. /opt/b1-mcp, npm ci --omit=dev as root) and run it with a root-owned node, never one under your home (nvm).
• Allow exactly that command with a sudoers rule (NOPASSWD, no extra arguments, no SETENV, environment reset), and set the MCP command to sudo -n -u b1mcp . Run creds through sudo -u b1mcp with your password, so only a human can add profiles or unlock.

This only holds if your user cannot become root without a password. Check for passwordless sudo, membership in the docker group, and on WSL the Windows in