Microsoft Business Central MCP Server

<img width="1536" height="1024" alt="mcp-business-central" src="https://github.com/user-attachments/assets/13932bfd-a5b9-4668-a7cd-ac9549a09673" />

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

1. Tenant ID: Find in Azure Portal → Azure Active Directory → Overview
2. Environment: Usually Production or Sandbox
3. 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:

{
  "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:

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

2. Generate Client Secret:

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

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

4. Verify Setup:

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

References:

• Microsoft: Service-to-service authentication
• Business Central API Authentication

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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