Microsoft Business Central MCP Server

适用于 Microsoft Dynamics 365 Business Central 的 Model Context Protocol (MCP) 服务器。通过格式正确的 API v2.0 调用，为 AI 助手提供对 Business Central 数据的直接访问。

功能特性

• ✅ 正确的 API URL：使用正确的 /companies(id)/resource 格式（无 ODataV4 段）

• ✅ 零安装：使用 npx 运行——无需预先安装

• ✅ Azure CLI 认证：利用现有的 Azure CLI 认证

• ✅ 客户端凭据认证：面向 AI 代理的服务到服务认证

• ✅ 简洁的工具名称：无前缀，只有 get_schema、list_items 等

• ✅ 完整 CRUD：创建、读取、更新和删除 Business Central 记录

安装

使用 npx（推荐）

无需安装！在 Claude Desktop 或 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"
      }
    }
  }
}

Windows 用户注意：如上所示，使用带 /c 的 cmd 以确保 npx 正确执行。

使用 Smithery

通过 Smithery 安装：

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

本地开发

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

配置

环境变量

获取配置值

1. 租户 ID：在 Azure Portal → Azure Active Directory → Overview 中查找

2. 环境：通常为 Production 或 Sandbox

3. 公司名称：Business Central 中显示的名称

示例 URL 格式：

https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0

认证

建议：使用 azure_cli 认证——设置更简单且更可靠。也支持 client_credentials 方法，但该方法在 Business Central 的 Microsoft Entra Applications 设置中存在已知配置难题。详见 docs/TROUBLESHOOTING.adoc。

选项 1：Azure CLI（推荐）

最简单且最可靠的认证方法。使用您现有的 Azure CLI 登录。

前提条件：

• 安装 Azure CLI：https://docs.microsoft.com/cli/azure/install-azure-cli

• 登录：az login

• 验证访问权限：az account get-access-token --resource https://api.businesscentral.dynamics.com

配置：

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

选项 2：客户端凭据（服务到服务）

适用于需要在无用户交互情况下运行的自动化系统。此方法使用 OAuth 2.0 客户端凭据流。

注意：此方法存在已知配置难题。Business Central 的“Microsoft Entra Applications”设置可能很复杂，应用程序用户的创建可能无法按预期工作。有关详细指导，请参阅 docs/TROUBLESHOOTING.adoc。

设置概述：

1. 创建 Azure 应用注册：

   • 转到 Azure Portal → Azure Active Directory → App registrations

   • 创建新注册（单租户）

   • 添加 API 权限：Dynamics 365 Business Central → app_access（应用程序权限，而非委派权限）

   • 为该权限授予管理员同意

   • 添加重定向 URI：https://businesscentral.dynamics.com/OAuthLanding.htm

2. 生成客户端机密：

   • 在您的应用注册中，转到 Certificates & secrets

   • 创建新的客户端机密并安全保存

3. 配置 Business Central：

   • 在 Business Central 中，搜索“Microsoft Entra Applications”

   • 单击 + New 并输入您应用的客户端 ID

   • 设置描述（这将成为应用程序用户名）

   • 将状态设置为“Enabled”——您应该会看到“将创建名为 '[Description]' 的用户”

   • 添加权限集：D365 BUS FULL ACCESS（推荐）或 D365 READ

   • 将 Company 字段留空以访问所有公司

   • 单击“Grant Consent”

4. 验证设置：

   • 应用程序用户应出现在 Business Central 的用户列表中

   • 如果没有，请参阅 docs/TROUBLESHOOTING.adoc 中的解决方案

参考：

• Microsoft：服务到服务认证

• Business Central API 认证

可用工具

1. get_schema

获取 Business Central 资源的 OData 元数据。

参数：

• resource（字符串，必填）：资源名称（例如 customers、contacts、salesOpportunities）

示例：

{
  "resource": "customers"
}

2. list_items

列出条目，支持可选过滤和分页。

参数：

• resource（字符串，必填）：资源名称

• filter（字符串，可选）：OData 过滤表达式

• top（数字，可选）：要返回的最大条目数

• skip（数字，可选）：分页时要跳过的条目数

示例：

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

3. get_items_by_field

获取与特定字段值匹配的条目。

参数：

• resource（字符串，必填）：资源名称

• field（字符串，必填）：用于过滤的字段名称

• value（字符串，必填）：要匹配的值

示例：

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

4. create_item

在 Business Central 中创建新条目。

参数：

• resource（字符串，必填）：资源名称

• item_data（对象，必填）：要创建的条目数据

示例：

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

5. update_item

更新现有条目。

参数：

• resource（字符串，必填）：资源名称

• item_id（字符串，必填）：条目 ID（GUID）

• item_data（对象，必填）：要更新的字段

示例：

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

6. delete_item

从 Business Central 删除条目。

参数：

• resource（字符串，必填）：资源名称

• item_id（字符串，必填）：条目 ID（GUID）

示例：

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

常用资源

• companies - 公司信息

• customers - 客户记录

• contacts - 联系人记录

• salesOpportunities - 销售机会

• salesQuotes - 销售报价

• salesOrders - 销售订单

• salesInvoices - 销售发票

• items - 产品/服务物料

• vendors - 供应商记录

故障排除

有关详细的故障排除指南，请参阅 docs/TROUBLESHOOTING.adoc，涵盖：

• 认证问题（401 错误、令牌问题）

• client_credentials 设置难题和已知问题

• 找不到公司的错误

• 特定于环境的配置（Production 与 Sandbox）

开发

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

许可证

MIT

贡献

欢迎在 https://github.com/knowall-ai/mcp-business-central 提交 Issue 和拉取请求

相关项目

• MCP 规范：modelcontextprotocol.io