![smithery badge](https://smithery.ai/server/@knowall-ai/mcp-business-central)

Microsoft Business Central MCP Server

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.

Features

✅ Correct API URLs: Uses proper /companies(id)/resource format (no ODataV4 segment)
✅ Zero Installation: Run with npx - no pre-installation required
✅ Azure CLI Auth: Leverages existing Azure CLI authentication
✅ Client Credentials Auth: Service-to-service authentication for AI agents
✅ Clean Tool Names: No prefixes, just get_schema, list_items, etc.
✅ Full CRUD: Create, read, update, and delete Business Central records

Installation

Using npx (Recommended)

No installation needed! Configure in Claude Desktop or Claude Code:

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/{environment}/api/v2.0",
        "BC_COMPANY": "Your Company Name",
        "BC_AUTH_TYPE": "azure_cli"
      }
    }
  }
}

Note for Windows: Use cmd with /c as shown above for proper npx execution.

Using Smithery

Install via Smithery:

npx -y @smithery/cli install @knowall-ai/mcp-business-central --client claude

Local Development

git clone https://github.com/knowall-ai/mcp-business-central.git
cd mcp-business-central
npm install
npm run build
node build/index.js

Configuration

Environment Variables

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | BC_URL_SERVER | Yes | Business Central API base URL | https://api.businesscentral.dynamics.com/v2.0/{tenant}/Production/api/v2.0 | | BC_COMPANY | Yes | Company display name | KnowAll Ltd | | BC_AUTH_TYPE | No | Authentication type (default: azure_cli) | azure_cli or client_credentials | | BC_TENANT_ID | For client_credentials | Azure AD tenant ID | 00000000-0000-0000-0000-000000000000 | | BC_CLIENT_ID | For client_credentials | App registration client ID | 00000000-0000-0000-0000-000000000000 | | BC_CLIENT_SECRET | For client_credentials | App registration client secret | your-secret-value |

Getting Your Configuration Values

Tenant ID: Find in Azure Portal → Azure Active Directory → Overview
Environment: Usually Production or Sandbox
Company Name: The display name shown in Business Central

Example URL format: `` https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0 ``

Authentication

Recommendation: Use azure_cli authentication - it's simpler to set up and more reliable. The client_credentials method is also supported but has known configuration challenges with Business Central's Microsoft Entra Applications setup. See docs/TROUBLESHOOTING.adoc for details.

Option 1: Azure CLI (Recommended)

The simplest and most reliable authentication method. Uses your existing Azure CLI login.

Prerequisites:

Install Azure CLI: https://docs.microsoft.com/cli/azure/install-azure-cli
Login: az login
Verify access: az account get-access-token --resource https://api.businesscentral.dynamics.com

Configuration: ``json { "mcpServers": { "business-central": { "type": "stdio", "command": "npx", "args": ["-y", "@knowall-ai/mcp-business-central"], "env": { "BC_AUTH_TYPE": "azure_cli", "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/Production/api/v2.0", "BC_COMPANY": "My Company" } } } } ``

Option 2: Client Credentials (Service-to-Service)

For automated systems that need to run without user interaction. This method uses OAuth 2.0 client credentials flow.

Note: This method has known configuration challenges. The Business Central "Microsoft Entra Applications" setup can be complex and the application user creation may not work as expected. See docs/TROUBLESHOOTING.adoc for detailed guidance.

Setup Overview:

Create Azure App Registration:

Go to Azure Portal → Azure Active Directory → App registrations
Create new registration (single tenant)
Add API permission: Dynamics 365 Business Central → app_access (Application permission, NOT Delegated)
Grant admin consent for the permission
Add redirect URI: https://businesscentral.dynamics.com/OAuthLanding.htm

Generate Client Secret:

In your app registration, go to Certificates & secrets
Create a new client secret and save it securely

Configure Business Central:

In Business Central, search for "Microsoft Entra Applications"
Click + New and enter your app's Client ID
Set a Description (this becomes the application user name)
Set State to "Enabled" - you should see "A user named '[Description]' will be created"
Add permission sets: D365 BUS FULL ACCESS (recommended) or D365 READ
Leave Company field blank for all companies access
Click "Grant Consent"

Verify Setup:

The application user should appear in the Users list in Business Central
If not, see docs/TROUBLESHOOTING.adoc for solutions

References:

Available Tools

1. `get_schema`

Get OData metadata for a Business Central resource.

Parameters:

resource (string, required): Resource name (e.g., customers, contacts, salesOpportunities)

Example: ``json { "resource": "customers" } ``

2. `list_items`

List items with optional filtering and pagination.

Parameters:

resource (string, required): Resource name
filter (string, optional): OData filter expression
top (number, optional): Maximum number of items to return
skip (number, optional): Number of items to skip for pagination

Example: ``json { "resource": "customers", "filter": "displayName eq 'Contoso'", "top": 10 } ``

3. `get_items_by_field`

Get items matching a specific field value.

Parameters:

resource (string, required): Resource name
field (string, required): Field name to filter by
value (string, required): Value to match

Example: ``json { "resource": "contacts", "field": "companyName", "value": "Contoso Ltd" } ``

4. `create_item`

Create a new item in Business Central.

Parameters:

resource (string, required): Resource name
item_data (object, required): Item data to create

Example: ``json { "resource": "contacts", "item_data": { "displayName": "John Doe", "companyName": "Contoso Ltd", "email": "john.doe@contoso.com" } } ``

5. `update_item`

Update an existing item.

Parameters:

resource (string, required): Resource name
item_id (string, required): Item ID (GUID)
item_data (object, required): Fields to update

Example: ``json { "resource": "customers", "item_id": "1366066e-7688-f011-b9d1-6045bde9b95f", "item_data": { "displayName": "Updated Name" } } ``

6. `delete_item`

Delete an item from Business Central.

Parameters:

resource (string, required): Resource name
item_id (string, required): Item ID (GUID)

Example: ``json { "resource": "contacts", "item_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" } ``

Common Resources

companies - Company information
customers - Customer records
contacts - Contact records
salesOpportunities - Sales opportunities
salesQuotes - Sales quotes
salesOrders - Sales orders
salesInvoices - Sales invoices
items - Product/service items
vendors - Vendor records

Troubleshooting

See docs/TROUBLESHOOTING.adoc for detailed troubleshooting guides covering:

Authentication issues (401 errors, token problems)
client_credentials setup challenges and known issues
Company not found errors
Environment-specific configuration (Production vs Sandbox)

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

License

MIT

Contributing

Issues and pull requests welcome at https://github.com/knowall-ai/mcp-business-central

Related Projects

MCP Specification: modelcontextprotocol.io

Microsoft Business Central MCP Server