How do I use business-central-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@business-central-mcp Show me the top 10 customers by sales this month" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

business-central-mcp

by masoniqbal777

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Overview

Property	Value
Language	TypeScript / Node 20+
npm package	`business-central-mcp`
BC versions	BC27, BC28 (wire-compatible)
Auth	NavUserPassword (OAuth on roadmap)
Tools	12
Tests	284 unit/protocol + 111 integration
License	MIT

Related MCP server: Microsoft Business Central MCP Server

Install

VSCode

Install in VSCode

Click the badge. VSCode opens, prompts to add the server, and writes to your user mcp.json.

You will still need to set BC_BASE_URL, BC_USERNAME, and BC_PASSWORD in the entry's env block. VSCode opens the file for you to edit.

Workspace: create .vscode/mcp.json:

{
  "servers": {
    "business-central": {
      "command": "npx",
      "args": ["-y", "business-central-mcp"],
      "env": {
        "BC_BASE_URL": "http://your-bc-server/BC",
        "BC_USERNAME": "your-user",
        "BC_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add business-central \
  -e BC_BASE_URL=http://your-bc-server/BC \
  -e BC_USERNAME=you \
  -e BC_PASSWORD=secret \
  -- npx -y business-central-mcp

Scope it to the current project with --scope project. See claude mcp --help for scoping options.

Claude Desktop

Download the latest .dxt from Releases.
Double-click. Claude Desktop opens Settings → Extensions and prompts for BC URL, username, and password.
Restart Claude Desktop.

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "business-central": {
      "command": "npx",
      "args": ["-y", "business-central-mcp"],
      "env": {
        "BC_BASE_URL": "http://your-bc-server/BC",
        "BC_USERNAME": "your-user",
        "BC_PASSWORD": "your-password"
      }
    }
  }
}

Restart Claude Desktop.

Configuration

Variable	Required	Default	Description
`BC_BASE_URL`	Yes	—	BC server base URL, e.g. `http://your-bc-server/BC`
`BC_USERNAME`	Yes	—	NavUserPassword username
`BC_PASSWORD`	Yes	—	NavUserPassword password
`BC_PROFILE`	No	server default	Profile id, e.g. `BUSINESS MANAGER`. Affects which Role Center loads and which pages Tell Me indexes.
`BC_TENANT_ID`	No	`default`	Multi-tenant deployments only.
`BC_CLIENT_VERSION`	No	`27.0.0.0`	Version reported to BC during session open.
`PORT`	No	`3000`	HTTP transport port (stdio transport ignores this).
`LOG_LEVEL`	No	`info`	`debug` / `info` / `warn` / `error`.
`LOG_DIR`	No	`./logs`	Directory for log files.
`STATE_DIR`	No	`./.state`	Directory for session state.
`BC_INVOKE_TIMEOUT`	No	`30000`	Per-invoke timeout in ms. Kills hung sessions.
`BC_RECONNECT_MAX_RETRIES`	No	`4`	Reconnect attempts after session death.
`BC_RECONNECT_BASE_DELAY`	No	`1000`	Base delay (ms) for exponential reconnect backoff.

What can it do?

Tool	What it does
`bc_open_page`	Open any page by ID -- lists, cards, documents, role centers. Returns the page as `sections[]` with header, lines, factboxes, and Role Center cuegroup tiles.
`bc_read_data`	Refresh a single section: filter, paginate, slice, project tab/columns. Returns the same `Section` shape as `bc_open_page`.
`bc_write_data`	Write field values; BC validates and echoes confirmed values. Section-aware (lines, factboxes, header).
`bc_execute_action`	Run header / row / wizard actions, OR drill down on Role Center cue tiles via `cue` input.
`bc_respond_dialog`	Handle confirmation prompts and request pages
`bc_navigate`	Select rows, drill down into records, field lookups
`bc_search_pages`	Tell Me search. Returns `{ name, objectType, runTarget, departmentPath, category, score }` per result.
`bc_close_page`	Close a page and free server resources
`bc_switch_company`	Switch to a different company mid-session
`bc_list_companies`	Discover available companies
`bc_run_report`	Execute reports and fill request page parameters
`bc_wizard_navigate`	Drive NavigatePage / wizard flows (back / next / finish / cancel)

How it works

This server speaks BC's internal WebSocket protocol directly -- the same protocol the browser-based web client uses. It was reverse-engineered from decompiled BC server assemblies. No OData endpoints, no SOAP services, no Selenium.

One WebSocket connection per session. All operations serialized through a promise queue. BC27 and BC28 are wire-compatible.

LLM (Claude / Copilot / etc.)
   |
   v   MCP (stdio or HTTP)
business-central-mcp
   |
   v   WebSocket + JSON-RPC
BC Web Service Tier (BC27 / BC28)
   |
   v   internal calls
BC Server

bc_open_page returns the page as a flat list of sections:

{
  "pageContextId": "session:page:21:abc",
  "pageType": "Card",
  "caption": "Customer Card",
  "isModal": false,
  "sections": [
    { "sectionId": "header",                       "kind": "header",  "fields": [...], "actions": [...] },
    { "sectionId": "factbox:Customer Statistics",  "kind": "factbox", "fields": [...] }
  ]
}

Each section carries its own content shape:

Card-style (header on Card pages, factbox, requestPage): fields[] and (for header) actions[]
List-style (lines on Documents, header on List pages, repeater subpages): rows[] and totalRowCount
Cue tiles (Role Center hosted CardParts): cues[] with each tile's name, value, groupCaption, synopsis, hasAction. Drill down with bc_execute_action { section, cue }.

bc_read_data returns a single Section for the requested sectionId (defaults to "header"). The section ID for a FactBox or subpage comes from the bc_open_page response.

Automatic reconnect with exponential backoff after session death
Handles BC's ~15s NTLM auth slot hold after crashes
Auto-dismisses license popups on fresh databases
Invoke timeout kills hung sessions and triggers recovery
Auto-recovery from LogicalModalityViolationException mid-session: reconciles the modal stack and retries transparently; falls back to session reset when BC keeps a confirm dialog sticky

Key files

File	Purpose
`src/stdio-server.ts`	npm `bin` entry -- stdio MCP transport
`src/server.ts`	HTTP MCP transport entry
`src/mcp/`	MCP tool registry, schemas, request handler
`src/operations/`	One handler per tool (`bc_open_page`, `bc_read_data`, etc.)
`src/services/`	Page, data, action, navigation, search business logic
`src/protocol/`	WebSocket transport, wire types, captures
`src/session/`	Session lifecycle, modal stack, reconnect
`manifest.json`	Claude Desktop Extension manifest
`scripts/build-dxt.ts`	Builds `.dxt` artifact for Claude Desktop
`.github/workflows/release.yml`	Builds + attaches `.dxt` on `v*` tag pushes
`ROADMAP.md`	Deferred work (OAuth, Cursor, init wizard)

Development

git clone https://github.com/SShadowS/business-central-mcp
cd business-central-mcp
npm install
npm run start:stdio-direct   # Run from source
npm test                     # 284 unit + protocol tests
npm run test:integration     # 111 integration tests against real BC (requires running BC server)

Roadmap

OAuth, Cursor support, an interactive init wizard, and a few protocol gaps. See ROADMAP.md for the full list and priorities.

Author: Torben Leth (sshadows@sshadows.dk) License: MIT (see LICENSE)

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Artificial Wit AIOAuth
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
ZapierOAuth
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
Airbyte AgentsOAuth
io.github.airbytehq
Let AI agents query data and act across all your business apps via MCP.
Data Platforms AI & Machine Learning RAG Systems
2
LeadDelta MCP ServerOAuth
io.github.LeadDelta
MCP server for LeadDelta — manage LinkedIn connections and CRM data via AI assistants.
Customer Data Platforms Social Media Marketing
2

Related MCP Servers

Microsoft Business Central MCP
ERP Systems CRM
knowall-ai
A
license
A
quality
D
maintenance
Model Context Protocol (MCP) server for Microsoft Dynamics 365 Business Central. Provides AI assistants with direct access to Business Central data through properly formatted API v2.0 calls.
Updated 3 months ago (2026-06-04 10:47 UTC)
6
8 npm
8
MIT
Microsoft Business Central MCP
ERP Systems CRM
MehrozeKhan73
A
license
A
quality
C
maintenance
MCP server for Microsoft Dynamics 365 Business Central that enables AI assistants to query and manage Business Central data via full CRUD operations.
Updated 2 months ago (2026-07-27 23:22 UTC)
6
8 npm
MIT
business-central-mcp
ERP Systems
EdwardHayes91
A
license
A
quality
C
maintenance
Gives AI assistants direct access to Microsoft Dynamics 365 Business Central via the native WebSocket protocol, replacing OData, APIs, and browser automation. Enables page navigation, data reading/writing, actions, searches, and report execution.
Updated a month ago (2026-08-10 15:45 UTC)
14
31 npm
MIT
Microsoft Business Central MCP
ERP Systems CRM
EdwardHayes91
A
license
B
quality
C
maintenance
MCP server for Microsoft Dynamics 365 Business Central, enabling AI assistants to perform CRUD operations, query data, and retrieve schemas via Business Central API v2.0.
Updated a month ago (2026-08-10 15:47 UTC)
6
8 npm
MIT