Microsoft Advertising MCP 连接器

适用于 Claude.ai 自定义连接器的独立 True Model B MCP 服务器。一个操作员可以连接多个 Microsoft 账户。每个连接可以查看多个 Microsoft Advertising 客户和广告账户。

这不是 Google All-in-One 连接器的一部分。它对该项目没有运行时依赖，不共享 Firestore 集合，也不共享 OAuth 令牌。

Claude.ai
   │  MCP OAuth 2.1
   ▼
operatorId
   ├── Microsoft Connection A → customers → advertising accounts → campaigns / reports
   ├── Microsoft Connection B
   └── Microsoft Connection C

MCP JWT sub 始终是内部 operatorId。Microsoft OpenID sub 仅存在于 bing_mcp_microsoft_connections.microsoftSubjectId 上。电子邮件是显示元数据，而非授权密钥。

架构

• Next.js 15 App Router + 位于 /mcp 的 mcp-handler Streamable HTTP

• MCP OAuth 2.1（使用 PKCE S256、DCR 和 Claude CIMD）

• Microsoft Entra 授权码流程（common 租户）

• Microsoft Advertising REST v13（非 SOAP）

• 命名 Firestore 数据库 bing-mcp-v1

• 刷新令牌的 AES-256-GCM 静态加密

• Cloud Run（无状态；监听 $PORT）

Related MCP server: Google Ads MCP Server

凭据（这些是不同的东西）

环境

将 .env.example 复制为 .env。切勿提交 .env。

必需项：

APP_BASE_URL
MICROSOFT_CLIENT_ID
MICROSOFT_CLIENT_SECRET
MICROSOFT_REDIRECT_URI
MICROSOFT_ADS_DEVELOPER_TOKEN
MCP_TOKEN_SECRET
OAUTH_STATE_SECRET
TOKEN_ENCRYPTION_KEY
FIRESTORE_PROJECT_ID
FIRESTORE_DATABASE_ID=bing-mcp-v1

FIRESTORE_DATABASE_ID 必须为 bing-mcp-v1。启动时会拒绝 (default) 和 gconnect-mcp-all-v1。

Microsoft Entra 应用注册

1. 打开 Microsoft Entra 应用注册。

2. 创建注册。

3. 受支持的账户类型：任何组织目录中的账户和个人 Microsoft 账户（因此 common 可用）。

4. 添加 Web 重定向 URI：{APP_BASE_URL}/oauth/microsoft/callback（本地示例：http://localhost:3000/oauth/microsoft/callback）。

5. 创建客户端机密。将其存储在 MICROSOFT_CLIENT_SECRET 中。

6. API 权限：Microsoft Advertising 委派范围 https://ads.microsoft.com/msads.manage。同时请求 openid、profile、email 和 offline_access。

7. 如果你的租户有要求，请授予管理员同意。

官方指南：

• 使用 OAuth 进行身份验证

• 请求用户同意

开发者令牌

从 Microsoft Advertising 开发者设置中获取 Microsoft Advertising 开发者令牌。沙盒令牌可以自行签发；生产令牌需要 Microsoft 批准。

此令牌是应用程序凭据。它在 Advertising REST 调用中作为 DeveloperToken 标头发送。它绝不会按操作员单独存储，也绝不能出现在 MCP 输出或日志中。

本地开发

npm install
npm test
npm run typecheck
npm run dev

• 健康检查：GET http://localhost:3000/health

• MCP：http://localhost:3000/mcp

• Microsoft 回调：http://localhost:3000/oauth/microsoft/callback

在 Claude.ai 中添加指向 {APP_BASE_URL}/mcp 的自定义连接器。Claude 完成 MCP OAuth 后，服务器会将浏览器重定向到 Microsoft 登录。同意后，继续返回 Claude。

本地 Firestore：使用 Application Default Credentials（gcloud auth application-default login）加 FIRESTORE_PROJECT_ID，或使用 FIRESTORE_EMULATOR_HOST。

MCP 工具（V1，只读）

连接：get_operator、list_microsoft_connections、get_microsoft_connection、start_microsoft_connection、disconnect_microsoft_connection

客户 / 账户：list_microsoft_customers、get_microsoft_customer、list_microsoft_accounts、get_microsoft_account

实体：list_campaigns、get_campaign、list_ad_groups、get_ad_group、list_ads、get_ad、list_keywords、get_keyword

报告（官方 Reporting API，异步提交/轮询/下载）：get_account_performance、get_campaign_performance、get_ad_group_performance、get_keyword_performance

如果同一个广告账户可通过多个 Microsoft 连接看到，服务器会返回歧义错误并要求提供 connectionId。它从不猜测。

Firestore 集合

命名数据库：bing-mcp-v1

• bing_mcp_operators

• bing_mcp_microsoft_connections

• bing_mcp_connection_uniques ({operatorId}_{microsoftSubjectId})

• bing_mcp_microsoft_customers

• bing_mcp_microsoft_accounts

• bing_mcp_oauth_transactions

• bing_mcp_sessions

Cloud Run

Cloud Run 入站流量必须无需身份验证。身份验证使用 MCP JWT，而非 Cloud IAM。

Cloud Run 服务账户需要对该命名数据库具有 Firestore 访问权限（通常为 roles/datastore.user）。使用 Application Default Credentials。不要提交服务账户 JSON 文件。

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-set-env.ps1 -ProjectId YOUR_PROJECT -AppBaseUrl https://... -MicrosoftClientId ... -MicrosoftClientSecret ... -McpTokenSecret ... -OauthStateSecret ... -TokenEncryptionKey ... -MicrosoftAdsDeveloperToken ...

然后将 {APP_BASE_URL}/oauth/microsoft/callback 添加到 Entra 应用，并在 {APP_BASE_URL}/mcp 添加 Claude 自定义连接器。

服务超时时间为 300 秒，以便异步报告能够完成。

安全

绝不通过 MCP 或日志暴露：访问令牌、刷新令牌、客户端机密、开发者令牌、加密密钥、授权码。

授权使用 operatorId + connectionId + Microsoft ID。名称和电子邮件不是授权标识符。

V2（未实现）

广告系列创建/更新/暂停、广告组和广告写入、关键字写入、预算更新。

测试

npm test

自动化测试涵盖 MCP JWT 身份、Microsoft OAuth 状态/交换/刷新/invalid_grant、操作员隔离、多连接、跨操作员的同一 Microsoft 身份、歧义账户拒绝、报告 CSV 解析、标头规则和机密脱敏。

实时 Claude、Microsoft 登录和 Cloud Run 路径需要你的 Entra 应用、开发者令牌和 GCP 项目。