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.

Related MCP server: Microsoft Business Central MCP Server

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 }.

Environment variables

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