mcp-microsoft-ads

非官方 — 与 Microsoft 无关联、未经其认可，也不受其支持。 这是一个面向 Microsoft Advertising 的第三方 MCP（Model Context Protocol）服务器。“MCP” 是一种开放协议，让 AI 助手（Claude 或任何其他 MCP 客户端）能够针对真实系统调用工具——在这里，就是你的 Microsoft Ads 账户。

安全优先的 Microsoft Ads MCP：47 个工具，涵盖广告系列、广告组、关键字、否定关键字、地理定向、广告计划、扩展、媒体、受众和转化目标管理，以及效果报告和 Ad Insight 关键字研究——构建它的目的是，让 AI 助手对真实广告账户拥有写入权限，并不意味着给它一张空白支票。

为什么“安全优先”

每个会修改数据的工具默认关闭。开启写入只需一个环境变量，即便如此，每一次写入在到达 Microsoft API 之前，都会经过同样的分层门禁：

1. MS_ADS_ENABLE_WRITES=true — 没有它，所有写入工具都会拒绝运行。开箱即用，这是一个只读服务器。

2. 草稿 → 确认。 写入工具绝不会在自身调用时修改数据。它会返回一个预览（一个 draft_id 以及将要发生的具体变更）；在你——或你的 MCP 客户端——调用 confirm_and_apply(draft_id) 之前，不会有任何实际变更。

3. 支出上限。 草稿创建和应用都会拒绝超过 MS_ADS_MAX_DAILY_BUDGET（默认 1000）或 MS_ADS_MAX_CPC（默认 50）的金额，以账户自身的货币计算，而非美元。

4. 智能出价失败即关闭的防护。 出价/调整写入被白名单限制为手动出价策略（ManualCpc、EnhancedCpc、ManualCpv、ManualCpm、ManualCpa）；无法识别或自动化的策略（MaxConversions、TargetCpa、TargetRoas 等）会被拒绝，而不是假定为安全。

5. JSONL 审计日志。 每个草稿和每次应用都会追加到一个本地、仅追加的 JSONL 文件中——这是该服务器实际所做操作的纯文本记录。

由 380+ 个离线测试（无实时 API 调用）支撑，这些测试针对模拟对象验证了防护机制、SOAP 管道细节以及草稿/确认生命周期。

诚实说明“草稿 → 确认”不是什么

草稿 → 确认是一个针对单次调用事故的预览门禁——出价中的拼写错误、复制粘贴错误、调用了错误的工具。它不是人工审批的访问控制：创建草稿的同一个 MCP 客户端可以立即调用 confirm_and_apply，服务器不要求有人工介入。如果你希望每次写入都有人工审核，那必须由你自己的工作流来强制执行（单独的审批步骤、仅限人工的客户端等）——这个服务器不会替你完成。

有一个写入操作被单独列出，因为上述分层机制无法完全约束它：apply_recommendation 将操作交给 Microsoft 决定的变更——你只能预览推荐 ID，而不是变更本身，因此实际产生的金钱影响不是这个服务器的支出上限可以提前检查的。它被保留（Microsoft 的推荐可能有用），被明确标注为特例，并且同时受 MS_ADS_ENABLE_WRITES 和它自己的独立标志 MS_ADS_ALLOW_APPLY_RECOMMENDATION 双重门控——因此，通常开启写入并不会同时开启这个操作。

这个服务器不做什么

• 没有质量得分诊断。

• 对临时 API 失败没有自动重试/退避（失败的调用就是失败；你需要重试）。

• 基于 Microsoft 的 SOAP Bing Ads SDK 构建，Microsoft 已宣布该 SDK 即将停止支持——见下文。

Related MCP server: OpenAI Ads MCP

SOAP 停止支持与 REST 路线图

这个服务器基于 bingads SOAP SDK 构建。Microsoft 已宣布 SOAP 将于 2027-01-31 停止支持，并建议在 2026-10-01 之前迁移（届时新 API 功能仅通过 REST 提供）。请参阅 Microsoft 的 迁移到 REST API 指南和 Python SDK SOAP 到 REST 迁移指南。将此服务器的工具移植到 REST 是路线图上的项目——SOAP 目前仍然可用，并且在 EOL 日期之前不会消失，但不要长期依赖它。

对比

对比最后检查于 2026-08-24。本项目不声称了解其他行的确切当前功能集，除了只读与非只读的区别——请查看每个项目自己的仓库/文档以了解详情。上述差异化特性（可选写入、两阶段草稿→确认、支出上限、智能出价失败即关闭防护、JSONL 审计日志、380+ 离线测试）是本项目构建的核心。

安装

git clone https://github.com/wvuhskr/mcp-microsoft-ads.git
cd mcp-microsoft-ads
python3 -m venv .venv  # requires Python >= 3.12
.venv/bin/pip install -e ".[dev]"

完整设置——Azure 应用注册、开发者令牌、首次 OAuth 登录——见 docs/setup.md。本节仅涵盖在凭据已存在的情况下运行服务器。

凭据

凭据存放在仓库之外的一个 YAML 文件中（默认 ~/.mcp-microsoft-ads/credentials.yaml，可通过 MS_ADS_CREDENTIALS_PATH 覆盖）：developer_token、client_id、client_secret、refresh_token、customer_id、account_id、tenant。

六个静态字段（除 refresh_token 之外的所有字段）也可以设置为 MS_ADS_DEVELOPER_TOKEN、MS_ADS_CLIENT_ID、MS_ADS_CLIENT_SECRET、MS_ADS_CUSTOMER_ID、MS_ADS_ACCOUNT_ID、MS_ADS_TENANT 环境变量——当两者都存在时，环境变量优先于文件。refresh_token 仅存在于文件中：Microsoft 每次使用都会轮换它，而轮换后的令牌必须持久化到某处以供下次运行，环境变量无法做到这一点。服务器会将每次轮换原子地写回凭据文件（保留一个 .bak 文件）。

首次运行演练

1. 引导登录：

   .venv/bin/python -m mcp_microsoft_ads.reauth

   在浏览器中引导交互式 OAuth 登录，并将生成的 refresh_token 写入凭据文件。此步骤依赖的 Azure 应用注册和开发者令牌，请参阅 docs/setup.md。

2. 以只读模式启动服务器（暂不设置 MS_ADS_ENABLE_WRITES），然后从你的 MCP 客户端调用 health_check，再调用 list_accounts 和/或 get_account_info。

3. 确认账户是你想要的那个——检查这些调用返回的账户 ID、账户名称和账户货币，与你打算让此服务器操作的账户进行核对。下面的支出上限是以该账户的货币强制执行的，因此货币不匹配值得在开启写入之前发现。

4. 然后才设置 MS_ADS_ENABLE_WRITES=true（如果你需要，还可以设置 MS_ADS_ALLOW_APPLY_RECOMMENDATION=true）并重启服务器。

MCP 客户端配置

两种配置都假设上述虚拟环境位于 ~/mcp-microsoft-ads/.venv——请将其替换为你机器上的实际绝对路径（两个客户端都需要绝对路径，而不是 ~）。

Claude Code（项目中的 .mcp.json，或通过 claude mcp add）：

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

不要让两个并发客户端指向同一个凭据文件

不支持在并发客户端之间共享一个凭据文件。 refresh_token 是一个轮换的、共享的、可变的文件：每次刷新都会生成一个新令牌并立即使旧令牌失效，而持久化轮换的读-修改-写操作无法在这一层安全地跨两个独立进程序列化。两个客户端同时从同一个文件刷新，可能会使彼此陷入令牌失效的困境。如果你需要多个并发客户端（例如同时打开 Claude Code 和 Claude Desktop），请为每个客户端提供自己的凭据文件和自己的 Azure 应用注册——为每个客户端设置不同的 MS_ADS_CREDENTIALS_PATH，并使用各自的 reauth 运行进行引导。

环境变量

货币说明： MS_ADS_MAX_DAILY_BUDGET 和 MS_ADS_MAX_CPC 直接与账户自身货币的金额进行比较，不进行与美元之间的换算。1000 的上限表示账户所用货币的 1000 个单位。

测试 / 代码检查

.venv/bin/python -m pytest -q     # offline test suite, ~370 tests, no live API calls
.venv/bin/python -m ruff check .  # lint

文档

• docs/setup.md — Azure 应用注册、开发者令牌、完整引导。

• SECURITY.md — 如何报告安全漏洞。

• CHANGELOG.md — 发布历史。

许可证与支持

采用 MIT 许可证——参见 LICENSE。这是一个尽力而为、无报酬的开源项目：不提供 SLA，不保证响应时间。Issue 会以尽力而为的方式被关注和分类处理。