使用说明

D365 OData MCP服务器

MCP（模型上下文协议）服务器，使AI助手能够查询 微软Dynamics 365 数据通过OData API。支持两者 数据空间 和 财务与运营（F&O）.

AI助理

如果你想让人工智能助手在帮助进行更改之前了解这个存储库，请让它阅读 AI_CONTEXT.md 第一。该文件简要概述了架构、运行时流程、MCP工具、安全规则和发布过程。

特性

✅ 完全支持OData查询： $filter, $select, $orderby, $top, $skip, $expand, $count
✅ 跨公司查询（F&O）
✅ Azure Active Directory 身份验证（Cloud D365）
✅ ADFS 身份验证（内部D365）
✅ 自动令牌刷新
✅ 使用指数回退重试
✅ 元数据缓存 具有可配置的TTL，可提高性能
✅ 适用于OpenAI Codex、Claude Desktop、Claude Code和其他MCP客户端

快速开始

步骤1：安装

cargo install d365-odata-mcp

升级到最新版本

cargo install d365-odata-mcp --force

步骤2：创建Azure AD应用程序

首选 Azure门户
导航至 微软Entra ID → 应用程序注册 → 新注册
命名您的应用程序（例如。， D365 MCP)
记下：
- 租户ID （摘自概览）
- 客户端ID （应用程序ID）
首选 证书和秘密 → 新客户机密 → 复制 秘密价值
首选 API权限 → 添加权限:
- 对于 数据空间: Dynamics CRM → user_impersonation
- 对于 F&O: Dynamics ERP → CustomService.FullAccess
点击 授予管理员同意

步骤3：配置您的AI客户端

在下面选择您的AI客户端：

这些示例是以下对象的快照 d365-odata-mcp。如果您正在排除故障 MCP连接或更新配置示例，请查看官方客户端文档首先，MCP配置结构和支持的传输可能会在外部发生变化这个仓库。

OpenAI Codex的配置

官方文件： OpenAI Codex MCP

食品法典委员会支持地方 stdio MCP服务器和流式HTTP MCP服务器。这服务器作为本地服务器运行 stdio 服务器。Codex CLI和Codex IDE扩展通过共享MCP配置 config.toml.

建议使用操作系统密钥存储进行本地设置：

codex mcp add d365 \
  --env TENANT_ID=your-tenant-id \
  --env CLIENT_ID=your-client-id \
  --env USE_KEYCHAIN=true \
  --env CLIENT_SECRET_KEYCHAIN_SERVICE=d365-odata-mcp-client-secret \
  --env ENDPOINT=https://your-org.crm.dynamics.com/api/data/v9.2/ \
  --env PRODUCT=dataverse \
  -- d365-odata-mcp

这 -- 将Codex MCP选项与本地选项分开 stdio 服务器命令。

要获得更细粒度的控制，请编辑 ~/.codex/config.toml.值得信赖项目，Codex也可以使用项目范围 .codex/config.toml:

[mcp_servers.d365]
command = "d365-odata-mcp"

[mcp_servers.d365.env]
TENANT_ID = "your-tenant-id"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
ENDPOINT = "https://your-org.crm.dynamics.com/api/data/v9.2/"
PRODUCT = "dataverse"

商店 `CLIENT_SECRET` 在操作系统密钥存储中

默认情况下， d365-odata-mcp 读取 CLIENT_SECRET 从MCP客户端的环境配置中。为了保守秘密 ~/.codex/config.toml，启用本地密钥存储查找：

[mcp_servers.d365]
command = "d365-odata-mcp"

[mcp_servers.d365.env]
TENANT_ID = "your-tenant-id"
CLIENT_ID = "your-client-id"
USE_KEYCHAIN = "true"
CLIENT_SECRET_KEYCHAIN_SERVICE = "d365-odata-mcp-client-secret"
ENDPOINT = "https://your-org.crm.dynamics.com/api/data/v9.2/"
PRODUCT = "dataverse"

秘密查找使用这对：

service = CLIENT_SECRET_KEYCHAIN_SERVICE
account = CLIENT_SECRET_KEYCHAIN_ACCOUNT, or CLIENT_ID when account is omitted

在macOS上，使用以下命令创建或更新Keychain项目：

security add-generic-password \
  -a "<CLIENT_ID>" \
  -s "d365-odata-mcp-client-secret" \
  -w "<CLIENT_SECRET>" \
  -U

如果您的Keychain项目使用了不同的帐户名，请设置 CLIENT_SECRET_KEYCHAIN_ACCOUNT 明确地：

USE_KEYCHAIN = "true"
CLIENT_SECRET_KEYCHAIN_SERVICE = "d365-odata-mcp-client-secret"
CLIENT_SECRET_KEYCHAIN_ACCOUNT = "shared-d365-app"

对于F&O：

[mcp_servers.d365]
command = "d365-odata-mcp"

[mcp_servers.d365.env]
TENANT_ID = "your-tenant-id"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
ENDPOINT = "https://your-org.sandbox.operations.dynamics.com/data/"
PRODUCT = "finops"

验证安装：

codex mcp list
codex mcp --help

在Codex终端UI中，使用 /mcp 查看活动的MCP服务器。

Claude代码的配置

官方文件：克劳德代码MCP

建议使用操作系统密钥存储进行本地设置：

claude mcp add --transport stdio --scope local d365 \
  --env TENANT_ID=your-tenant-id \
  --env CLIENT_ID=your-client-id \
  --env USE_KEYCHAIN=true \
  --env CLIENT_SECRET_KEYCHAIN_SERVICE=d365-odata-mcp-client-secret \
  --env ENDPOINT=https://your-org.crm.dynamics.com/api/data/v9.2/ \
  --env PRODUCT=dataverse \
  -- d365-odata-mcp

这 -- 将Claude Code选项与MCP服务器命令分开论据。将本地作用域用于您不希望使用的凭据支持的配置在存储库中共享。

对于共享项目配置，请创建 .mcp.json 并在操作系统中保守秘密秘密商店：

{
  "mcpServers": {
    "d365": {
      "type": "stdio",
      "command": "d365-odata-mcp",
      "env": {
        "TENANT_ID": "${TENANT_ID}",
        "CLIENT_ID": "${CLIENT_ID}",
        "USE_KEYCHAIN": "true",
        "CLIENT_SECRET_KEYCHAIN_SERVICE": "d365-odata-mcp-client-secret",
        "ENDPOINT": "https://your-org.crm.dynamics.com/api/data/v9.2/",
        "PRODUCT": "dataverse"
      }
    }
  }
}

使用以下工具进行管理和调试：

claude mcp list
claude mcp get d365

在Claude Code内部，使用 /mcp 检查连接状态。如果D365响应如果较大，请使用较大的输出预算启动Claude Code：

MAX_MCP_OUTPUT_TOKENS=50000 claude

Claude桌面配置

官方文件：连接到本地MCP服务器

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "d365": {
      "command": "d365-odata-mcp",
      "env": {
        "TENANT_ID": "your-tenant-id",
        "CLIENT_ID": "your-client-id",
        "USE_KEYCHAIN": "true",
        "CLIENT_SECRET_KEYCHAIN_SERVICE": "d365-odata-mcp-client-secret",
        "ENDPOINT": "https://your-org.crm.dynamics.com/api/data/v9.2/",
        "PRODUCT": "dataverse"
      }
    }
  }
}

谷歌反重力2.0的配置

官方文件：谷歌反重力MCP

Antigravity 2.0使用专用 mcp_config.json 顶级文件 mcpServers 对象。您可以全局或按工作区配置此服务器：

全球的： ~/.gemini/config/mcp_config.json
工作区： .agents/mcp_config.json

在《反重力2.0》中，打开设置 → 定制 → 已安装的MCP服务器.在Antigravity IDE中，打开代理侧面板菜单 (...) → MCP服务器 → 管理MCP服务器 → 查看原始配置. 在Antigravity CLI中，键入 /mcp 打开交互式MCP管理器。

建议使用操作系统密钥存储区进行Webex配置：

{
  "mcpServers": {
    "d365": {
      "command": "d365-odata-mcp",
      "env": {
        "TENANT_ID": "your-tenant-id",
        "CLIENT_ID": "your-client-id",
        "USE_KEYCHAIN": "true",
        "CLIENT_SECRET_KEYCHAIN_SERVICE": "d365-odata-mcp-client-secret",
        "ENDPOINT": "https://your-org.crm.dynamics.com/api/data/v9.2/",
        "PRODUCT": "dataverse"
      }
    }
  }
}

建议使用操作系统机密存储的F&O配置：

{
  "mcpServers": {
    "d365-finops": {
      "command": "d365-odata-mcp",
      "env": {
        "TENANT_ID": "your-tenant-id",
        "CLIENT_ID": "your-client-id",
        "USE_KEYCHAIN": "true",
        "CLIENT_SECRET_KEYCHAIN_SERVICE": "d365-odata-mcp-client-secret",
        "ENDPOINT": "https://your-org.sandbox.operations.dynamics.com/data/",
        "PRODUCT": "finops"
      }
    }
  }
}

如果必须使用每个环境的钥匙扣项目，请设置服务和帐户明确地：

{
  "mcpServers": {
    "d365": {
      "command": "d365-odata-mcp",
      "env": {
        "TENANT_ID": "your-tenant-id",
        "CLIENT_ID": "your-client-id",
        "USE_KEYCHAIN": "true",
        "CLIENT_SECRET_KEYCHAIN_SERVICE": "d365-odata-mcp-client-secret",
        "CLIENT_SECRET_KEYCHAIN_ACCOUNT": "shared-d365-app",
        "ENDPOINT": "https://your-org.crm.dynamics.com/api/data/v9.2/",
        "PRODUCT": "dataverse"
      }
    }
  }
}

用于本地 stdio MCP服务器，如 d365-odata-mcp，使用 command, args, env，并且可选 cwd反重力的远程MCP配置使用 serverUrl 用于流式HTTP或SSE服务器。

可用工具

1. `list_entities`

列出所有可用的D365实体：

"List all D365 entities"

2. `query_entity`

具有完全OData支持的查询数据：

参数	说明	必填
`entity`	实体名称。， `CustomersV3`	✅
`filter`	OData过滤器。， `dataAreaId eq 'bc'`	❌
`select`	要返回的字段。， `Name,Id`	❌
`orderby`	排序顺序。， `CreatedDate desc`	❌
`top`	最大记录数（默认值：50，最大值：1000）	❌
`skip`	要跳过的记录（分页）	❌
`expand`	要展开的导航属性	❌
`cross_company`	`true` 适用于跨公司（仅F&O）	❌
`count`	`true` 包括总计数	❌

示例：

"Query CustomersV3, show first 10 records"
"Query SalesOrderHeaders where dataAreaId is 'bc', order by SalesOrderNumber desc"
"Get inventory where warehouse is 'WH01' with count"

3. `get_entity_schema`

获取实体的可用字段：

"Show schema for SalesOrderHeaders"

4. `get_record`

按ID获取单个记录：

"Get customer record with ID 'CUS-001'"

5. `delete_record`

按OData键删除单个记录。此工具需要 confirm 确切地说 DELETE.

参数	说明	必填
`entity`	实体名称。， `CustomersV3`	✅
`key`	无括号的OData密钥表达式。， `dataAreaId='bc',CustomerAccount='CUS-001'`	❌
`id`	简单记录ID/密钥，用于 `key` 未提供	❌
`if_match`	可选 `If-Match` 标头值（默认值： `*`)	❌
`confirm`	必须完全正确 `DELETE`	✅

例子：

"Delete CustomersV3 with key dataAreaId='bc',CustomerAccount='CUS-001' and confirm DELETE"

6. `get_environment_info`

获取D365环境信息：

"Show D365 environment info"

7. `get_metadata`

获取实体元数据，包括属性和导航属性（可扩展字段）：

"Get metadata for CustomersV3"
"Show me the schema and expandable fields for SalesOrderHeaders"

8. `refresh_metadata`

强制刷新缓存的元数据（架构更改时有用）：

"Refresh metadata cache"

环境变量

变量	描述	必填
`TENANT_ID`	Azure AD租户ID（或 `adfs` 对于ADFS）	✅
`CLIENT_ID`	Azure AD/ADF应用程序ID	✅
`CLIENT_SECRET`	Azure AD/ADF客户端密码	✅ 除非 `USE_KEYCHAIN=true`
`ENDPOINT` D365 OData 端点网址✅
`PRODUCT`	`dataverse` 或 `finops`	✅
`AUTH_TYPE`	`azure` （默认）或 `adfs`	❌
`TOKEN_URL`	自定义令牌URL（仅限ADFS）	❌
`RESOURCE`	资源/受众（仅限ADFS）	❌
`METADATA_CACHE_TTL`	元数据缓存TTL（秒）（默认值：900=15分钟）	❌
`INSECURE_SSL`	跳过自签名证书的SSL验证(`true`/`false`)	❌
`USE_KEYCHAIN`	阅读 `CLIENT_SECRET` 来自操作系统本机密钥存储(`true`/`false`，默认值 `false`)	❌
`CLIENT_SECRET_KEYCHAIN_SERVICE`	在以下情况下使用的秘密商店服务名称 `USE_KEYCHAIN=true`	✅ 当 `USE_KEYCHAIN=true`
`CLIENT_SECRET_KEYCHAIN_ACCOUNT`	秘密商店帐户名称；默认为 `CLIENT_ID` 如果省略	❌

本地D365（ADFS）的配置

对于具有ADFS身份验证的D365 F&O内部部署：

# ~/.codex/config.toml

[mcp_servers.d365_onprem]
command = "d365-odata-mcp"

[mcp_servers.d365_onprem.env]
AUTH_TYPE = "adfs"
TENANT_ID = "adfs"
CLIENT_ID = "your-adfs-client-id"
CLIENT_SECRET = "your-adfs-secret"
TOKEN_URL = "https://your-adfs-server.com/adfs/oauth2/token"
RESOURCE = "https://your-d365-onprem.com"
ENDPOINT = "https://your-d365-onprem.com/namespaces/AXSF/data/"
PRODUCT = "finops"

常见F&O实体

实体	描述
`CustomersV3`	客户主数据
`VendorsV2`	供应商主数据
`ProductsV2`	产品主数据
`SalesOrderHeaders`	销售订单标题
`SalesOrderLines`	销售订单行
`PurchaseOrderHeaders`	采购订单标题
`PurchaseOrderLines`	采购订单行
`InventoryOnHandAggregatedByWarehouse`	现有库存

OData筛选器语法

操作员	示例
`eq`	`Status eq 'Open'`
`ne`	`Status ne 'Closed'`
`gt` / `ge`	`Amount gt 1000`
`lt` / `le`	`Amount lt 100`
`and` / `or`	`Status eq 'Open' and Amount gt 100`
`contains`	`contains(Name, 'Corp')`
`startswith`	`startswith(Name, 'ABC')`

测试

直接测试服务器：

export TENANT_ID="..." CLIENT_ID="..." CLIENT_SECRET="..." ENDPOINT="..." PRODUCT="finops"
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | d365-odata-mcp

许可证

MIT许可证-请参阅许可证了解详情。

贡献

欢迎投稿！请打开问题或提交PR。

使用说明

D365 OData MCP服务器

AI助理

特性

快速开始

步骤1：安装

升级到最新版本

步骤2：创建Azure AD应用程序

步骤3：配置您的AI客户端

OpenAI Codex的配置

商店 CLIENT_SECRET 在操作系统密钥存储中

Claude代码的配置

Claude桌面配置

谷歌反重力2.0的配置

可用工具

1. list_entities

2. query_entity

3. get_entity_schema

4. get_record

5. delete_record

6. get_environment_info

7. get_metadata

8. refresh_metadata

环境变量

本地D365（ADFS）的配置

常见F&O实体

OData筛选器语法

测试

许可证

贡献

相关 MCP

CRM数据访问协议服务器

项目上下文管理服务器

搜索引擎数据集成服务

Intersight MCP 服务器

Dataverse API服务器

AI助手协议服务器