d365-bc-mcp

A read-only MCP server for Dynamics 365 Business Central. It gives Claude Code, Claude Desktop, or any MCP client governed access to live ERP data — customers, items, orders, invoices, and any other BC API entity — without ever being able to change anything.

Built by an IT admin who wanted AI assistance over production ERP data and refused to hand an LLM write access to the general ledger to get it.

Every tool issues GET requests only. Nothing is created, modified, or deleted in Business Central, by construction — there is no code path that issues a write.

Design

• Read-only by construction, then again by permission. The server only performs GETs, and the recommended setup also runs under an identity that BC itself restricts to read-only permission sets. Two independent layers; either alone would hold.
• Dual auth, auto-selected. Personal use gets delegated device-code auth (BC sees you, your permissions apply). Shared/deployed use gets client-credentials with a dedicated Entra app. Set one env var to switch.
• Two transports. stdio for local MCP clients; stateless Streamable HTTP (--http) for remote/shared use, with optional bearer-key protection.
• Boring dependencies. TypeScript, @modelcontextprotocol/sdk, MSAL, Express, Zod. No framework, ~2.5k lines, readable in one sitting.

Mode	When	How it authenticates
device_code (default)	BC_CLIENT_SECRET empty	Delegated — you sign in once as yourself; BC sees your user and your BC permissions apply
client_credentials	BC_CLIENT_SECRET set	Service-to-service — a dedicated Entra app with its own (read-only) BC permission set

Prerequisites

• Node.js 20+
• A Business Central online tenant and an Entra app registration:
  • Device-code mode: a public-client app registration — Authentication → Allow public client flows: Yes, plus the delegated Dynamics 365 Business Central / user_impersonation API permission. If your org already has one (many BC integrations create one), you can reuse it.
  • Client-credentials mode: see Service-to-service setup below.

Quick start (device code)

git clone https://github.com/vinaybabuv/d365-bc-mcp
cd d365-bc-mcp
npm install
npm run build
cp .env.example .env   # then edit: tenant ID, client ID, environment, company

Sign in once, then verify the pipe end to end:

node --env-file=.env dist/index.js login
node --env-file=.env dist/index.js test

login runs the device-code flow (open the URL, enter the code) and caches tokens at %LOCALAPPDATA%\d365-bc-mcp\token-cache.json (override with BC_TOKEN_CACHE) — refresh is silent from then on. test lists companies and three sample customers to prove auth, environment, and company selection all work.

Hook up to Claude Code

claude mcp add bc \
  --env BC_TENANT_ID=<your-tenant-guid> \
  --env BC_CLIENT_ID=<your-app-client-id> \
  --env BC_ENVIRONMENT=Production \
  --env "BC_COMPANY_NAME=CRONUS USA, Inc." \
  -- node /path/to/d365-bc-mcp/dist/index.js

(Add --scope user to make it available in every project.)

Hook up to Claude Desktop

Add to claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS) under mcpServers:

{
  "mcpServers": {
    "business-central": {
      "command": "node",
      "args": ["/path/to/d365-bc-mcp/dist/index.js"],
      "env": {
        "BC_TENANT_ID": "<your-tenant-guid>",
        "BC_CLIENT_ID": "<your-app-client-id>",
        "BC_ENVIRONMENT": "Production",
        "BC_COMPANY_NAME": "CRONUS USA, Inc."
      }
    }
  }
}

Service-to-service setup (for a shared connector)

For a connector that runs without a signed-in user (deployed to a server, used by a team), create a dedicated app registration:

Task 1 — Entra (entra.microsoft.com → App registrations → New):

1. Single tenant, no redirect URI needed.
2. Certificates & secrets → New client secret — copy the value immediately.
3. API permissions → Add → Microsoft APIs → Dynamics 365 Business Central → Application permissions → API.ReadWrite.All → Add, then Grant admin consent. (The permission name says ReadWrite, but actual data access is governed by the BC permission set you assign in Task 2 — assign a read-only one.)

Task 2 — Business Central:

1. In BC, search Microsoft Entra Applications → New.
2. Paste the app's Application (client) ID, set State = Enabled.
3. Assign a read-only permission set (e.g. D365 READ plus the specific read sets your data needs). Least privilege is the point: even though the server never writes, the identity it runs as shouldn't be able to.

Then: set BC_CLIENT_ID to the new app's ID and BC_CLIENT_SECRET to the secret. The server switches to client-credentials mode automatically. Verify with node --env-file=.env dist/index.js test.

HTTP mode (remote / shared use)

node --env-file=.env dist/index.js --http

Serves stateless Streamable HTTP at http://localhost:3010/mcp (PORT to change), plus GET /healthz. Set MCP_API_KEY to require Authorization: Bearer <key> on every MCP request — do this for anything beyond localhost, and put real TLS in front of anything beyond your machine.

Connect Claude Code to it:

claude mcp add --transport http bc http://localhost:3010/mcp --header "Authorization: Bearer <MCP_API_KEY>"

Note on claude.ai custom connectors: claude.ai (Settings → Connectors) requires either an unauthenticated URL or OAuth — it cannot send a static bearer header. To expose this server there, put an OAuth layer in front (Entra ID works; claude.ai supports manually-entered client credentials), or use Microsoft's hosted Business Central MCP server instead. Claude Code and Claude Desktop work fine with the bearer-key approach.

Tools

All list tools accept top (default 20, max 100) and skip, and return { total_count, returned, has_more, records }.

Tool	What it does
bc_list_companies	Companies visible to this connection
bc_list_customers	Customers; search on name or raw OData filter
bc_get_customer	One customer by number or GUID
bc_list_items	Items; search/filter (e.g. inventory lt 10)
bc_list_vendors	Vendors; search/filter
bc_list_sales_orders	Orders; by customer, status, date range
bc_get_sales_order	One order incl. lines, by number or GUID
bc_list_sales_invoices	Invoices; by customer, status, dates, unpaid_only
bc_get_sales_invoice	One invoice incl. lines, by number or GUID
bc_query	Read-only escape hatch: GET any BC API entity (salesShipments, purchaseOrders, generalLedgerEntries, …) or custom APIs via api_route: "publisher/group/version"

Environment variables

Var	Required	Notes
BC_TENANT_ID	yes	Entra tenant GUID
BC_CLIENT_ID	yes	App registration client ID
BC_CLIENT_SECRET	no	Setting it switches to client-credentials mode
BC_AUTH_MODE	no	Explicit override: device_code | client_credentials
BC_ENVIRONMENT	no	BC environment name, default Production
BC_COMPANY_NAME	no	Working company; auto-selected if the identity sees exactly one
BC_TOKEN_CACHE	no	Token cache path (device-code mode)
MCP_API_KEY	no	HTTP mode: require this bearer token
PORT	no	HTTP mode port, default 3010

Security notes

• No secrets in code or in this repo — configuration is environment-only, and .env / token caches are git-ignored.
• Delegated mode inherits the signed-in user's BC permissions; it can never see more than that user could.
• Client-credentials mode should run under a BC permission set that is read-only, so the transport-level GET-only guarantee is backed by an authorization-level one.
• The HTTP transport is stateless and unauthenticated by default for localhost development; set MCP_API_KEY (and TLS) before exposing it anywhere else.

License

MIT