Skip to main content
Glama
SShadowS

business-central-mcp

by SShadowS
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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

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

  1. Download the latest .dxt from Releases.

  2. Double-click. Claude Desktop opens Settings → Extensions and prompts for BC URL, username, and password.

  3. 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 installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SShadowS/business-central-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server