bing-ads

Bing Ads MCP 服务

适用于 Microsoft Advertising（Bing Ads）API 的生产级 MCP 服务。支持 Claude 管理 Bing/Microsoft Ads 账户，并提供完整的广告系列、广告组、关键词管理和效果分析功能。

功能：

• 10 个工具——经过生产环境测试
• 广告系列、广告组和关键词管理
• 带质量得分的关键词效果分析
• 搜索词报告和出价自动化
• 预算和出价策略优化
• 广告系列级预算更新
• 否定关键词管理（共享级和广告系列级）

注意： ⚠️ 首个提供全面工具的开源 Bing Ads MCP

• 该生态系统中没有成熟的替代方案
• 已在多个账户中经过实战检验

安装

npm install mcp-bing-ads

配置

安全： 切勿分享 .mcp.json 文件或将其提交到 git——该文件可能包含 API 凭据。将 .mcp.json 添加到 .gitignore。

1. 获取 OAuth 凭据：

   • 前往 Microsoft Azure Portal
   • 创建 Azure AD 应用注册
   • 授予 API 权限：Microsoft Advertising API
   • 作用域：https://ads.microsoft.com/msads.manage offline_access

2. 创建 config.json：

   cp config.example.json config.json
   

3. 填写凭据：

   {
     "oauth": {
       "client_id": "YOUR_AZURE_CLIENT_ID",
       "client_secret": "YOUR_AZURE_CLIENT_SECRET"
     },
     "clients": {
       "default": {
         "customer_id": "YOUR_CUSTOMER_ID",
         "account_id": "YOUR_ACCOUNT_ID",
         "name": "My Account"
       }
     }
   }
   

4. 设置环境变量（推荐）：

   export BING_ADS_DEVELOPER_TOKEN="your_developer_token"
   export BING_ADS_CLIENT_ID="your_client_id"
   export BING_ADS_REFRESH_TOKEN="your_refresh_token"
   # Optional:
   export BING_ADS_CLIENT_SECRET="your_client_secret"
   # Optional: opt into mutating tools (read-only by default)
   export BING_ADS_MCP_WRITE="true"
   

环境变量

变量	必需	默认值	说明
BING_ADS_DEVELOPER_TOKEN	是	--	Microsoft Advertising 开发者令牌
BING_ADS_CLIENT_ID	是	--	Azure AD 应用客户端 ID
BING_ADS_REFRESH_TOKEN	是	--	OAuth 刷新令牌
BING_ADS_CLIENT_SECRET	否	--	Azure AD 应用客户端密钥（适用于机密客户端）
BING_ADS_MCP_WRITE	否	false	设置为 true、1 或 yes，以启用修改类工具（暂停/更新/添加）。任何其他值或未设置时，服务均保持只读。

默认只读

除非在服务环境中设置 BING_ADS_MCP_WRITE=true，否则修改类工具（bing_ads_pause_keywords、bing_ads_update_campaign_budget、bing_ads_add_shared_negatives）不会显示在工具列表中，且调用时会被拒绝。这是为了防止随意执行写入操作，例如根据临时聊天消息暂停关键词或修改预算。要进行写入更改，请在需要的会话中将环境变量明确设置在 .mcp.json 或 shell 配置文件中，之后再取消设置。读取工具（列表/报告/效果）始终可用。

使用方法

启动服务

npm start

与 Claude Code 配合使用

添加到 ~/.claude.json：

{
  "mcpServers": {
    "bing-ads": {
      "type": "http",
      "url": "http://localhost:3002"
    }
  }
}

Claude Desktop： 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

API 调用示例

// Get client context
bing_ads_get_client_context({ working_directory: "/path/to/project" })

// List campaigns
bing_ads_list_campaigns()

// Get campaign performance
bing_ads_get_campaign_performance({
  start_date: "2026-01-01",
  end_date: "2026-03-01"
})

// Get keyword performance
bing_ads_keyword_performance({
  start_date: "2026-02-01",
  end_date: "2026-03-01"
})

// Create negative keywords
bing_ads_add_shared_negatives({
  shared_list_id: "list_123",
  keywords: [
    { text: "cheap", match_type: "Phrase" },
    { text: "discount", match_type: "Exact" }
  ]
})

API 参考

上下文

• bing_ads_get_client_context(working_directory) -- 根据工作目录检测账户

广告系列

• bing_ads_list_campaigns() -- 列出所有广告系列
• bing_ads_get_campaign_performance(start_date, end_date) -- 广告系列指标
• bing_ads_update_campaign_budget(campaign_id, daily_budget) -- 更新每日支出

广告组

• bing_ads_list_ad_groups(campaign_id) -- 列出广告系列中的广告组

关键词

• bing_ads_keyword_performance(start_date, end_date, [campaign_ids]) -- 关键词指标和 QS
• bing_ads_search_term_report(start_date, end_date) -- 触发广告展示的搜索词
• bing_ads_pause_keywords(ad_group_id, keyword_ids) -- 暂停关键词

否定关键词

• bing_ads_list_shared_entities([type]) -- 列出共享否定关键词列表
• bing_ads_add_shared_negatives(list_id, keywords) -- 添加到共享列表

效果报告

• 广告系列效果（投资回报率、转化次数、点击率、每次点击费用）
• 关键词效果（QS、预期点击率、广告相关性、着陆页体验）
• 搜索词洞察（哪些查询带来了转化）

关键指标与定义

质量得分（QS）： 对关键词质量的 1-10 评分

• 1-3：较差
• 4-6：一般
• 7-10：优秀

预期点击率： 对预期点击率的 1-9 评分 广告相关性： 对广告与搜索查询相关程度的 1-9 评分 着陆页体验： 对着陆页质量的 1-9 评分

CLI 工具

npm run dev                 # Run in dev mode (tsx)
npm run build             # Compile TypeScript
npm test                  # Run contract tests

架构

文件：

• src/index.ts — MCP 服务、OAuth 流程、工具处理程序
• src/tools.ts — 工具架构定义
• src/errors.ts — 错误处理与分类
• config.json — 凭据与客户端映射

错误分类：

• 身份验证错误（令牌已过期）
• 速率限制错误（采用退避策略重试）
• 服务错误（API 暂时不可用）
• 验证错误（输入无效）

开发

添加新工具

1. 在 src/tools.ts 中定义架构
2. 在 src/index.ts 的工具分发逻辑中添加处理程序
3. 在 .contract.test.ts 中添加契约测试
4. 使用 npm test 进行测试

测试

npm test -- --run        # Single run
npm test -- --watch      # Watch mode

故障排除

Config file not found

cp config.example.json config.json
# Fill in your Azure credentials and Bing Ads IDs

Missing required credentials

请检查以下内容：

• 已设置 BING_ADS_DEVELOPER_TOKEN、BING_ADS_CLIENT_ID 和 BING_ADS_REFRESH_TOKEN
• 已设置 BING_ADS_CLIENT_SECRET（如果使用机密应用）
• OAuth 令牌有效（令牌会过期，可能需要刷新）

Rate limit exceeded

Bing Ads 设有速率限制。服务会自动处理常见的重试情况。如果频繁触及限制：

• 尽可能批量执行操作
• 降低查询频率
• 等待一段时间后再重试

Quality Score is 0

QS = 0 表示关键词的展示次数还不够。请增加展示次数，或等待更多数据。

许可证

MIT

贡献

欢迎贡献！请：

1. 为新功能添加测试
2. 更新 README
3. 遵循现有代码风格
4. 为发布版本添加标签

支持

• 问题： 在 GitHub Issues 中报告错误或提交功能请求
• 文档： 详细 API 参考请参阅 docs/ 文件夹
• 社区： GitHub Discussions

---

作者

Mark Harnett — 需求开发负责人和付费媒体从业者，致力于构建 AI 驱动的广告管理工具。这是首个全面的开源 Bing Ads MCP 服务，源于管理多个账户中的真实广告系列，并希望让 Claude 承担繁重工作。

本项目面向生产工作负载构建：具备弹性的 API 调用（熔断器、退避重试、响应截断）、完整的质量得分诊断，以及大规模否定关键词管理。

Mark 的其他项目： mcp-linkedin-ads -- 包含 7 个工具的 LinkedIn Ads MCP 服务。

最后更新： 2026-03-13