使用说明

业务中心MCP服务器

Microsoft Dynamics 365 Business Central的模型上下文协议服务器。

将AI代理连接到Business Central数据——从单个 npx 命令为开发人员提供完整的企业Azure部署。

两种使用方法

	npm（开发人员）	Azure（企业）
用例	本地AI助手、开发、原型制作	生产云服务、多租户
运输 .stdin/stdout、HTTP/SSE。
客户	Claude Desktop、Claude Code、Cline、Cursor	Claude.ai、Copilot Studio、Azure ai Foundry
设置时间	2分钟	15分钟
基础设施	无（本地运行）	Azure容器应用

快速入门：npm（开发者模式）

选项A:npx（不安装）

npx business-central-mcp-server --stdio

选项B：全局安装

npm install -g business-central-mcp-server
business-central-mcp-server --stdio

在Claude桌面中配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "business-central": {
      "command": "npx",
      "args": ["-y", "business-central-mcp-server", "--stdio"],
      "env": {
        "BC_TENANT_ID": "<your-tenant-id>",
        "BC_CLIENT_ID": "<your-client-id>",
        "BC_CLIENT_SECRET": "<your-client-secret>",
        "BC_ENVIRONMENT_NAME": "Sandbox",
        "BC_COMPANY_ID": "<your-company-id>"
      }
    }
  }
}

在Claude代码中配置

创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "business-central": {
      "command": "npx",
      "args": ["-y", "business-central-mcp-server", "--stdio"],
      "env": {
        "BC_TENANT_ID": "<your-tenant-id>",
        "BC_CLIENT_ID": "<your-client-id>",
        "BC_CLIENT_SECRET": "<your-client-secret>",
        "BC_ENVIRONMENT_NAME": "Sandbox",
        "BC_COMPANY_ID": "<your-company-id>"
      }
    }
  }
}

CLI参数

您可以将配置作为CLI参数传递，而不是环境变量：

business-central-mcp-server --stdio \
  --tenantId <tenant-id> \
  --clientId <client-id> \
  --clientSecret <client-secret> \
  --environment Sandbox \
  --companyId <company-id>

获取您的凭据

Azure AD应用程序注册 --在Azure门户中注册应用程序>应用程序注册
API权限 --添加 Dynamics 365 Business Central > API.ReadWrite.All （应用程序权限）
客户端密钥 --在证书和机密下创建
租户ID --在应用程序注册概述页面上找到
公司ID --使用 list_companies 连接后使用该工具，或在BC管理中心找到它

快速入门：Azure（企业模式）

用于为云AI客户端（Claude.AI、Copilot Studio、Azure AI Foundry）提供服务的生产部署。

先决条件

Azure订阅
具有API访问权限的Business Central租户
Azure AD应用程序注册（请参阅部署指南)

部署

使用GitHub Actions工作流或手动部署：

git clone https://github.com/olederkach/business-central-mcp-server.git
cd business-central-mcp-server

# Deploy to Azure Container Apps (see docs/DEPLOYMENT.md for full walkthrough)

部署的内容：

Azure容器应用程序（自动扩展，1-10个副本）
Azure容器注册表
应用洞察（遥测，可选）

身份验证模式

模式	服务器 `AUTH_MODE`	使用案例
OAuth	`oauth`	Claude.ai，Copilot工作室（用户级身份验证）
API密钥	`api-key`	Azure AI Foundry，简单集成

连接Claude.ai（OAuth）

Claude.ai > Settings > MCP Servers > Add Custom
  Name: Business Central
  URL: https://<your-server>.azurecontainerapps.io/mcp
  Client ID: <your-azure-client-id>
  Client Secret: <your-azure-client-secret>

连接Copilot Studio（OAuth动态发现）

Copilot Studio > Knowledge > Add knowledge > MCP
  Name: BC-MCP-Server
  URL: https://<your-server>.azurecontainerapps.io/mcp
  Auth: OAuth 2.0 > Dynamic discovery
  Client ID: <your-azure-client-id>
  Client Secret: <your-azure-client-secret>
  Scope: api://<your-azure-client-id>/.default openid

连接Azure AI Foundry（API密钥）

Settings > Connections > + New connection > MCP
  Endpoint: https://<your-server>.azurecontainerapps.io/mcp
  Authentication: API Key (X-API-Key header)

看文档/部署.md 获取完整的部署指南和 docs/MCP_CLIENT_SETUP.md 适用于所有客户端配置。

工具（14）

API上下文管理

工具	描述	类型
`list_bc_api_contexts`	发现可用的API路由	只读
`set_active_api`	切换发布者/组/版本	状态更改
`get_active_api`	获取当前API上下文	只读

公司管理层

工具	描述	类型
`list_companies`	列出所有不列颠哥伦比亚省公司	只读
`set_active_company`	切换活动公司	状态更改
`get_active_company`	获取当前公司	只读

资源发现

工具	描述	类型
`list_resources`	列出所有实体名称	只读
`get_odata_metadata`	搜索OData架构	只读
`get_resource_schema`	获取实体字段和类型	只读

CRUD操作

工具	描述	类型
`list_records`	使用OData筛选器/排序/页面进行查询	只读
`create_record`	创建新记录	破坏性
`update_record`	修补现有记录（ETag支持）	破坏性
`delete_record`	永久删除记录	破坏性
`find_records_by_field`	按字段值搜索	只读

示例

User: "Show me customers in Atlanta"

Tool call: list_records
Arguments: { "resource": "customers", "filter": "city eq 'Atlanta'", "top": 10 }

Multi-API支持

Business Central公开多个API曲面。此服务器支持所有这些功能：

标准BC API v2.0 --客户、供应商、商品、销售订单等。
Microsoft扩展API --自动化、分析
自定义ISV API --第三方扩展API

运行时切换：

set_active_api({ publisher: "microsoft", group: "automation", version: "v1.0" })

配置

环境变量

必需（两种模式）

变量	描述
`BC_TENANT_ID`	Azure AD租户GUID
`BC_CLIENT_ID`	应用注册客户端ID
`BC_CLIENT_SECRET`	应用注册客户端密码
`BC_ENVIRONMENT_NAME`	`Sandbox` 或 `Production`

企业版（仅限HTTP模式）

变量	默认值	描述
`MCP_API_KEYS`	-	用于客户端身份验证的逗号分隔的API密钥
`AUTH_MODE`	`api-key`	`api-key` 或 `oauth`
`CORS_ORIGINS`	`*`	允许的来源
`PORT`	`3005`	HTTP端口
`KEY_VAULT_NAME`	--	用于机密的Azure密钥库
`APPLICATIONINSIGHTS_CONNECTION_STRING`	--	监控
`RATE_LIMIT_ENABLED`	`true`	启用速率限制

看 .env.示例以供完整参考。

建筑

                    ┌──────────────────────────────┐
                    │        AI Clients             │
                    │  Claude Desktop/Code (stdio)  │
                    │  Copilot Studio (HTTP)        │
                    │  Azure AI Foundry (HTTP)      │
                    └──────────┬───────────────────┘
                               │
              ┌────────────────┼────────────────┐
              │ stdio          │                │ HTTP/SSE
              ▼                │                ▼
    ┌─────────────────┐        │    ┌─────────────────────────┐
    │  stdio-server    │        │    │  Express + MCP Protocol  │
    │  (npm/npx)       │        │    │  (Azure Container Apps)  │
    │                  │        │    │                          │
    │  14 Generic      │        │    │  API Key / OAuth Auth    │
    │  Tools           │        │    │  Rate Limiting           │
    └────────┬────────┘        │    │  App Insights            │
             │                 │    └───────────┬──────────────┘
             │                 │                │
             └────────────────┼────────────────┘
                               │
                               ▼
                    ┌──────────────────────────────┐
                    │  Business Central API         │
                    │  OAuth 2.0 (client_credentials)│
                    │  OData V4.0                   │
                    └──────────────────────────────┘

关键组件

组件	npm模式	企业模式
传输	stdio（stdin/stdout）	HTTP+SSE
工具	14通用工具	14一般工具+特定实体
Auth（BC）	OAuth客户端证书	OAuth客户端认证证书
Auth（客户端）	N/A（本地进程）	neneneba API密钥或OAuth
状态	进行中（会话映射）	按请求
监控	stderr日志	应用程序洞察
机密	环境变量/CLI参数	Azure密钥库

发展

本地设置

git clone https://github.com/olederkach/business-central-mcp-server.git
cd business-central-mcp-server
npm install

# Configure
cp .env.example .env
# Edit .env with your BC credentials

# Development (stdio)
npm run dev:stdio

# Development (HTTP)
npm run dev:http

# Production build
npm run build
npm start

构建和打包

npm run build          # Compile TypeScript
npm pack               # Create .tgz for local install
npm link               # Symlink for local development

项目结构

src/
├── index.ts                  # Entry point (stdio/HTTP dispatcher)
├── version.ts                # Centralized version constant
├── config.ts                 # CLI args + env var parsing
├── server.ts                 # Express HTTP server
├── api/                      # API context & company management
├── auth/                     # Authentication (OAuth, API Key, DCR)
├── bc/                       # Business Central client & metadata
├── config/                   # Environment validation
├── errors/                   # Error codes & builders
├── mcp/                      # MCP protocol handler & prompts
├── middleware/                # Express middleware
├── monitoring/               # App Insights & analytics
├── openapi/                  # OpenAPI spec generation
├── tools/                    # Tool definitions & executors
│   ├── generic-tools.ts      # 14 generic tool definitions
│   ├── generic-executor.ts   # Generic tool executor
│   ├── executor.ts           # Entity-specific executor (HTTP mode)
│   └── generator.ts          # Tool generator from metadata
├── transports/               # stdio, SSE, Copilot SSE servers
└── utils/                    # Logger, validators, sanitizer

故障排除

Copilot Studio UI中“无可用工具”

预计采用MCP协议2024-11-05。工具在运行时工作——从聊天界面进行测试。

“身份验证失败”

npm模式：验证 BC_CLIENT_ID, BC_CLIENT_SECRET，以及 BC_TENANT_ID
企业：还要检查 MCP_API_KEYS 和 X-API-Key 头球

“无法连接到Business Central”

验证Azure AD应用程序注册是否已 Dynamics 365 Business Central > API.ReadWrite.All
确认应用程序已获得管理员同意

直接测试凭据：

curl -X POST "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
  -d "client_id=<client-id>&client_secret=<secret>&scope=https://api.businesscentral.dynamics.com/.default&grant_type=client_credentials"

“未找到公司”

跑 list_companies 首先获取可用的公司ID，然后使用 set_active_company 或设置 BC_COMPANY_ID.

文档

文档	描述
部署.md	Azure部署指南
快速启动.md	5分钟快速启动
Copilot工作室设置	Copilot Studio集成
Azure AI Foundry	Azure AI Foundry设置
API 参考	OData参数、错误、限制
建筑	ADR和设计决策
安全.md	安全策略
更改日志.md	版本历史

许可证

麻省理工学院——见许可证

链接

专为商务中心和人工智能社区打造。