Adbutler

AdButler MCP 服务

通过任意 AI 助手管理整个 AdButler 账户，包括 Claude、ChatGPT、Cursor、Windsurf、Cline，以及其他任何 Model Context Protocol 客户端。

此 MCP 服务开放了完整的 AdButler v2 API，包含 600 多个工具，涵盖广告主、广告系列、广告位、创意素材、投放位置、VAST 视频广告、程序化广告 / RTB、报告、定向、草稿、合同、产品目录等；此外还提供 9 个预置工作流提示词，引导 AI 完成发起广告系列或设置零售媒体等常见任务。

可以询问什么

“为 Pepsi 创建一个新的广告系列，定向加拿大用户，终身预算为 $5,000，并将其分配到我的 Homepage Banner 广告位。”

“显示过去 7 天 CTR 表现最差的前 10 个广告项。”

“设置一个 VAST 4.2 前贴片广告系列，包含一个可跳过的 30 秒创意素材和三个伴随横幅。”

“指导我创建新的程序化交易。”

“审核我的广告单元——哪些广告位没有有效的投放位置？”

AI 会将这些请求转换为正确的 AdButler API 调用序列，执行调用并显示结果。

安装

有两种选择。大多数用户适合使用托管版本——无需任何设置，只需粘贴 URL。

选项 A — 托管版（推荐）

使用 AdButler 的托管 MCP 服务。无需安装，无需 Node，也无需 npm。

托管服务同时支持现代 Streamable HTTP（/mcp）和旧版 SSE（/sse）传输方式。新客户端应优先使用 Streamable HTTP；SSE 仍可用于向后兼容。

客户端	配置
Claude Desktop / Code	添加 MCP 服务，URL 填写 https://mcp.adbutler.com/mcp（旧版客户端可使用 /sse），并添加请求头 Authorization: Bearer YOUR_ADBUTLER_API_KEY
Cursor	Settings → Features → Model Context Protocol → 添加服务，并填写上述 URL 和身份验证请求头
任意 MCP 客户端	Streamable HTTP：https://mcp.adbutler.com/mcp  ·  SSE：https://mcp.adbutler.com/sse — 通过 Authorization: Bearer … 或 ?api_key=… 传递 API 密钥

选项 B — 本地 stdio（npm）

在本地将服务作为 Node 进程运行。如果你希望避免 API 密钥经过任何外部服务，或要连接到可自托管的 AdButler，此选项会很有用。

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "adbutler": {
      "command": "npx",
      "args": ["-y", "@adbutler/mcp-server"],
      "env": {
        "ADBUTLER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add adbutler --env ADBUTLER_API_KEY=your_api_key_here -- npx -y @adbutler/mcp-server

Cursor / Windsurf / Cline

添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "adbutler": {
      "command": "npx",
      "args": ["-y", "@adbutler/mcp-server"],
      "env": { "ADBUTLER_API_KEY": "your_api_key_here" }
    }
  }
}

获取 AdButler API 密钥

AdButler Dashboard → Settings → API Keys → 创建新密钥。该密钥与 AdButler v2 REST API 使用的密钥相同。

身份验证

AdButler MCP 适用于新老客户。你看到的内容取决于是否已经配置 API 密钥。

已经是 AdButler 客户？（已有 API 密钥）

选择以下任一方式：

选项 1 — 在连接配置中设置 API 密钥（推荐：可跨会话保留）

连接时传入密钥，之后每个会话都会自动完成身份验证，无需在聊天中分享密钥。

• Claude Code — claude mcp add adbutler --transport http https://mcp.adbutler.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
• Claude Desktop — 编辑 claude_desktop_config.json → 在服务 URL 旁添加 headers: { "Authorization": "Bearer YOUR_API_KEY" }
• Cursor — MCP 服务设置 → Headers → 添加 Authorization: Bearer YOUR_API_KEY
• claude.ai 自定义连接器（不支持自定义标头）— 使用 URL 格式：https://mcp.adbutler.com/mcp?api_key=YOUR_API_KEY
• 任何客户端 — 在 /mcp（Streamable HTTP）或 /sse（旧版 SSE）上使用 Authorization: Bearer … 标头或 ?api_key=… 查询参数

重新连接后，即可立即使用全部 600 多个工具。

选项 2 — 在聊天中配置（托管服务上仅限当前会话）

无需身份验证即可连接到托管 MCP 服务，你会看到四个引导工具。然后在聊天中输入：

“配置我的 AdButler API 密钥：your_api_key_here”

你的 AI 会调用 setup_api_key 工具，根据你的账户验证密钥并解锁所有 AdButler 工具。之后你可能需要断开连接并重新连接，以刷新客户端的工具列表。

⚠️ 在托管服务上，以这种方式配置的密钥仅在会话结束前有效——新聊天、客户端重启或服务端重新连接后，都会要求你再次提供密钥。如果你发现自己反复在聊天中粘贴密钥（而且 AI 还提醒你不要在对话中分享机密信息），请改用选项 1：在连接设置中配置一次密钥，即可永久保留。

故障排除：“我的 API 密钥无法保持配置状态”

这意味着你在聊天中（选项 2）向托管服务输入了密钥。托管服务会刻意将密钥的作用范围限定在当前会话内——托管服务采用多租户架构，绝不会将你的密钥写入磁盘。解决方法是在客户端连接配置中进行一次性设置（见上文选项 1）：Claude Code / Claude Desktop / Cursor 使用标头，claude.ai 自定义连接器使用 ?api_key= URL 参数。完成后，重新连接和新聊天都会自动进行身份验证。

刚接触 AdButler？（尚无账户）

无需身份验证即可连接到托管 MCP 服务。聊天会引导你通过 create_trial_account 注册免费试用 → 查看电子邮件 → 使用验证码调用 verify_trial_email。API 密钥会自动配置。

本地 stdio 安装

如果你通过 npx 在本地运行，请在客户端 MCP 配置的 env 块中设置 ADBUTLER_API_KEY（见上文选项 B）。设置工具同样可用，而且本地环境会在不同会话之间保留密钥。

包含内容

9 个工作流提示词

预先构建的技能提示词，可引导 AI 端到端完成完整工作流。在客户端中将它们作为 MCP 提示词调用（例如 /launch-campaign）。

提示词	功能
launch-campaign	端到端引导广告活动启动流程——广告主 → 广告活动 → 广告项 → 创意素材 → 定向 → 广告位
retail-media-setup	为电商网站设置赞助商品 / 零售媒体
reporting	使用合适的维度和筛选条件生成自定义报告
vast-video	构建包含线性创意素材和伴随创意素材的 VAST 视频广告
programmatic	配置程序化交易、竞价方和需求来源
targeting	构建地理位置 / 平台 / 数据键 / 列表定向
contracts	创建 IO 合同并将其分配给广告活动
channels	将广告区域组合为频道并分配广告活动
drafts	将完整广告活动暂存为草稿，然后再正式投放

3 个后备元工具（搜索、描述、调用）

当你需要的端点没有专用工具封装，或用户询问的是某个字段（例如“优先级”“频次上限”）而非资源时，可以使用这 3 个应急工具来弥补空缺：

工具	功能
search_adbutler_api	在完整的 AdButler OpenAPI 规范中按关键词搜索匹配的端点
describe_adbutler_api	获取某个端点的完整架构（参数、请求体、响应）
call_adbutler_api	按方法和路径调用任意端点，并自动应用会话身份验证

这些工具与下方的专用工具相辅相成（而非取代它们）——当专用工具明显匹配时，大模型仍会优先使用专用工具。

覆盖完整 AdButler API 的 600 多个工具

领域	工具数	示例
展示广告	100+	list_advertisers、create_campaign、create_image_ad_item、create_native_ad_item、create_placement、create_schedule、create_campaign_assignment
VAST 2/3/4 视频	156	vast_create_creative、vast_create_linear_media、vast_create_companion、vast_create_placement、vast_create_schedule，以及完整的 VAST 4.2 子资源覆盖
广告位与发布	50+	create_zone、create_zone_catalog、create_zone_email、create_native_template、create_publisher、ORTB 原生素材
定向	37	create_geo_target、create_platform_target、create_data_key、create_data_list、create_postal_code_target
报告	39	get_display_report、get_vast_report、get_event_logs、自定义报告配置、定时报告
程序化广告 / RTB	25	create_demand_source、create_demand_endpoint、create_bidder、create_pmp_deal
产品目录	20	create_product_db_catalog、bulk_upload_products、广告项与目录项关联
草稿	48	将广告活动、广告项、广告位和排期暂存为草稿；原子化发布
合同	43	广告投放订单、合同文件、签名请求、付款
账户与安全	27	用户、角色、重定向域名、信标签名密钥、SFTP 连接
广告投放	2	serve_ad、live_website_preview

覆盖 AdButler v2 OpenAPI 规范的 100%（604/604 个端点）。

遥测

mcp.adbutler.com 上的托管服务会收集使用情况分析数据，以便我们了解哪些工具最受欢迎、确定改进优先级并诊断故障。每次工具调用会记录：

• 工具名称（例如 list_zones、create_campaign）——绝不记录工具参数
• 账户 ID（每个会话根据 /self 获取一次）
• API 密钥指纹（SHA-256，截取前 16 个十六进制字符）——用于识别所用密钥，不会存储密钥本身
• 传输方式（HTTP 或 SSE）、MCP 客户端名称和版本（例如 Claude Desktop）、调用耗时、成功 / 错误状态
• 发生错误时：上游 HTTP 状态码、错误类别（例如 forbidden、network）以及错误消息文本（截断至 1000 个字符）

我们绝不收集：工具参数、响应正文、原始 API 密钥、IP 地址、请求正文。监测机制只能看到工具名称、耗时，以及（发生故障时）MCP 服务或 AdButler API 生成的错误消息。

自行安装的副本——npm 包、stdio、自行部署的实例——不会收集任何数据。 只有在设置了 ANALYTICS_INGEST_URL 环境变量时，监测机制才会运行；而该变量仅在 mcp.adbutler.com 上的托管端点中设置。

如果你希望退出托管服务的分析数据收集，可以通过 stdio 运行自己的副本，或自行托管 SSE/HTTP 服务。

开发

供贡献者使用的本地源码：

git clone https://github.com/adbutler/mcp-server
cd mcp-server
npm install
npm run build
ADBUTLER_API_KEY=your_key node dist/index.js

使用官方 MCP 检查器进行检查：

npx @modelcontextprotocol/inspector node dist/index.js

Resources

• AdButler API documentation — https://api.adbutler.com/openapi.json
• MCP Protocol — https://modelcontextprotocol.io
• Hosted server status — https://mcp.adbutler.com/health
• Issues / feature requests — https://github.com/adbutler/mcp-server/issues

License

MIT