Search Ads 360 MCP Server

Cesteral MCP 服务

可自托管的主流广告平台 MCP 连接器。

如果您需要透明的平台集成、本地试用，以及由您掌控的基础设施，请使用此仓库。如果您的团队需要在支出提交前审批、凭证托管、可审计性，以及在统一的受管控环境中执行跨平台操作，请使用 Cesteral Intelligence。

在本地试用 Meta Ads MCP（约 10 分钟） | 比较开源版与 Cesteral Intelligence | 预约工作流演示

                                

---

两种使用方式

此仓库是一个开放的连接器层，并非完整产品。

• 自托管连接器，以透明地直接掌控您的凭证、基础设施和平台访问权限。
• 如果工作流需要受管控的写入操作、团队审批、凭证托管、可审计性和跨平台协调，请使用 Cesteral Intelligence——请参阅下文的何时需要使用。

---

旗舰连接器

Google Ads MCP

通过 Google Ads REST API v25 执行广告系列写入、GAQL 报告、出价调整、预览和验证。

软件包文档 | 与 Cesteral Intelligence 搭配使用

Meta Ads MCP

通过 Meta Marketing API v26.0 执行广告系列写入、洞察查询、定向探索、投放估算、预览和批量操作。

软件包文档 | 与 Cesteral Intelligence 搭配使用

DV360 MCP

通过 DV360 API v4 执行广告系列写入、定向设置、自定义出价、预览、上传，以及基于架构的验证。

软件包文档 | 与 Cesteral Intelligence 搭配使用

---

何时需要 Cesteral Intelligence

OSS 连接器提供按服务器执行工具并记录审计日志。Cesteral Intelligence 在此基础上添加治理和编排功能：

• 凭据代理 -- 将平台机密信息排除在本地操作员工作流之外
• 审批工作流 -- 在进行破坏性更改或高成本更改前，要求人工审核
• 汇总审计 -- 统一的跨服务器活动动态，包含来源信息，并关联到操作员身份
• 跨平台编排 -- 协调多个连接器之间受治理的执行
• 团队运营 -- 共享工作流、租户隔离和操作员可见性

比较 OSS 连接器与 Cesteral Intelligence

---

完整服务阵容

服务器	平台	工具	身份验证
gads-mcp	Google Ads REST API v25	18	OAuth2 刷新令牌
meta-mcp	Meta Marketing API v26.0	27	Bearer 令牌
dv360-mcp	DV360 API v4	26	Google OAuth2 / 服务账号
ttd-mcp	The Trade Desk REST + GraphQL API	46	用户令牌（TTD-Auth header）
linkedin-mcp	LinkedIn Marketing API (202608)	23	Bearer 令牌
tiktok-mcp	TikTok Marketing API v1.3	25	Bearer 令牌 + 广告主 ID
cm360-mcp	CM360 API v5	22	Google OAuth2
sa360-mcp	SA360 Reporting API v0 + DS v2	17	OAuth2 刷新令牌
pinterest-mcp	Pinterest Ads API v5	24	Bearer 令牌
snapchat-mcp	Snapchat Ads API v1	25	Bearer 令牌
amazon-dsp-mcp	Amazon Ads Unified API (DSP)	28	Bearer 令牌
msads-mcp	Microsoft Advertising API v13	28	访问令牌 + 开发者令牌
dbm-mcp	Bid Manager API v2	6	Google OAuth2

共有 13 个服务、290 多个工具。工具数量是每个服务当前注册的总数， 包括适用时的 *_search_tools 发现工具。

每个服务都提供的功能

每个服务都支持 MCP 协议修订版 2025-03-26、2025-06-18 和 2025-11-25，这些是 @modelcontextprotocol/sdk 1.31.0 实现的版本；Streamable HTTP 传输会拒绝任何其他 MCP-Protocol-Version。当前修订版 2026-07-28 尚不受支持 （#242）。

这并非完整规范。在 MCP 一致性测试套件 （@modelcontextprotocol/conformance 0.1.16）中，每个服务都通过了 30 个有效服务场景中的 18 个——初始化、ping、日志级别和日志通知、工具列表和调用、征询（表单、默认值和枚举）、资源列表、读取和模板、提示词列表和获取、并发 SSE 流、DNS 重绑定防护——而 conformance/expected-failures.yaml 列出了其余 12 项未通过的原因。尚未实现：补全、资源订阅、采样、进度通知、图像／音频／嵌入式资源内容，以及 SSE 流恢复。征询请求（包括下文的破坏性操作确认）和日志通知会通过发起 tools/call 请求的响应流发送，因此客户端无需使用可选的 GET 流也能接收它们。绑定到环回地址的服务（NODE_ENV=production 以外环境下的默认设置）仅接受 /mcp 上的环回 Host 和 Origin 标头；绑定到其他地址的服务仅在设置了 MCP_ALLOWED_HOSTS 时检查 Host。

除原始工具调用外，每个服务还提供：

• MCP 提示词 — 按需提供多步骤工作流指导（广告活动启动、报告、故障排查），帮助 Agent 无需重新摸索每个平台的操作顺序。全部 13 个服务均提供。
• MCP 资源 — 结构化且可寻址的上下文（架构、字段目录、示例、枚举），按需获取，避免每个工具的架构过于臃肿。全部 13 个服务均提供。DV360 使用这些资源，避免将超过 1 MB 的判别联合类型通过网络传输（entity-schema://、entity-fields://、entity-examples://）。
• 工具发现 — <platform>_search_tools 工具，让 Agent 按意图搜索服务自身的目录，而非翻阅完整列表。13 个服务中有 10 个提供（小型的 gads-mcp 和 sa360-mcp，以及仅用于报告的 dbm-mcp 除外）。
• 服务发现卡片 — 每个服务均在所有认证模式下，于 /.well-known/mcp/server-card.json 提供 SEP-2127 元数据（名称、版本、传输方式、认证模式、功能）。
• OAuth 资源发现 — 在 jwt 认证模式下，于 /.well-known/oauth-protected-resource 提供 RFC 9728 端点。
• 报告 CSV 溢出存储 — 较大的报告正文会存储到 GCS，并通过签名 URL 提供，以限制响应大小。适用于报告量较大的六个服务：ttd-mcp、tiktok-mcp、snapchat-mcp、amazon-dsp-mcp、pinterest-mcp、msads-mcp。

服务	发现	提示词	资源	CSV 溢出存储
gads-mcp		✅	✅
meta-mcp	✅	✅	✅
dv360-mcp	✅	✅	✅
ttd-mcp	✅	✅	✅	✅
linkedin-mcp	✅	✅	✅
tiktok-mcp	✅	✅	✅	✅
cm360-mcp	✅	✅	✅
sa360-mcp		✅	✅
pinterest-mcp	✅	✅	✅	✅
snapchat-mcp	✅	✅	✅	✅
amazon-dsp-mcp	✅	✅	✅	✅
msads-mcp	✅	✅	✅	✅
dbm-mcp		✅	✅

---

面向生产环境构建

自托管一个会影响实时广告支出的 AI Agent，首先是信任问题，其次才是能力问题。以下两点让这套服务群无需手动构建防护措施，也能安全用于生产环境：

• 审计级可观测性。每次工具调用都会以仅追加的 JSONL 格式记录。发生故障时，还会记录完整的上游 HTTP 轨迹——每个请求、每次重试、每个响应——并在源头对机密信息进行脱敏。托管部署可直接在 BigQuery 中查询；自托管则可将标准输出接入现有日志系统。 阅读可观测性指南。
• 破坏性操作的用户确认门控。十二个具备写入能力的服务中（dbm-mcp 仅用于报告），有 51 个破坏性工具会在执行删除、批量状态更改、出价调整、预算更改、转化上传和异步 Workflows 批处理任务前提示用户。Stdio 和不支持用户确认的客户端将遵循文档规定的非交互式约定。少于 10 项的批量修改会跳过提示，除非涉及敏感字段（状态／预算／出价）。
• 可验证的发布来源。受治理的工具带有规范的 SHA-256 definitionHash（来自 @cesteral/contract-hash），并写入各软件包的 cesteral-manifest.json。带标签的版本会通过构建来源证明发布到 npm，并在 tarball 中以传递方式签署清单，以便下游治理系统准确验证发布的工具定义，并将匹配的工具提升为 attested 信任级别。

如果你的安全审查需要证据——脱敏列表、字段架构、上游捕获路径、契约哈希——本仓库中都有。

---

快速开始

如需分步指南，请参阅10 分钟快速入门。

前置条件

• Node.js >= 20.0.0
• pnpm >= 10.0.0 -- corepack enable 会从 packageManager 获取固定版本（或运行 npm install -g pnpm@10）
• Docker（用于容器化）
• Terraform >= 1.6.0 （用于部署）

1. 克隆并安装

git clone https://github.com/cesteral/mcp-open-advertising.git
cd mcp-open-advertising
pnpm install

2. 构建

pnpm run build

3. 在本地运行服务

# Start any server using the dev script
./scripts/dev-server.sh gads-mcp    # port 3004
./scripts/dev-server.sh meta-mcp    # port 3005
./scripts/dev-server.sh dv360-mcp   # port 3002

# See each package README for required environment variables

4. 配置你的 AI Agent

{
  "mcpServers": {
    "cesteral-gads": {
      "url": "https://gads.your-domain.com/mcp",
      "apiKey": "your-gads-api-key"
    },
    "cesteral-meta": {
      "url": "https://meta.your-domain.com/mcp",
      "apiKey": "your-meta-api-key"
    }
  }
}

按需添加服务即可。每个服务都会独立运行，也可以单独部署。

5. 部署

cd terraform
terraform init
terraform apply -var-file=dev.tfvars

生产环境设置请参阅部署指南。

---

架构

Cesteral 采用 GCP 原生架构，由十三个可独立部署的 Cloud Run MCP 服务组成。每个服务都通过 HTTPS 在 Cloud Run 上直接提供 MCP 协议。

关键设计决策：

• 单一云服务提供商（GCP）：Cloud Run、BigQuery、Pub/Sub、Secret Manager——统一监控，每月约 150-220 美元
• 直接使用 HTTP 传输：无需边缘网关层
• 独立部署：每个服务都可以单独部署和扩展
• 可组合：可使用一个服务，也可使用全部十三个——它们既能独立运行，也能协同工作

AI 客户端通过 HTTPS 直接连接一个或多个 MCP 服务；无需配置共享网关。使用 Cesteral Intelligence 时，它会在同一套服务群之上提供租户管理、凭据、审批和治理能力。

仓库结构

mcp-open-advertising/
├── packages/
│   ├── gads-mcp/          # Google Ads
│   ├── meta-mcp/          # Meta Ads
│   ├── dv360-mcp/         # DV360
│   ├── ttd-mcp/           # The Trade Desk
│   ├── linkedin-mcp/      # LinkedIn Ads
│   ├── tiktok-mcp/        # TikTok Ads
│   ├── cm360-mcp/         # Campaign Manager 360
│   ├── sa360-mcp/         # Search Ads 360
│   ├── pinterest-mcp/     # Pinterest Ads
│   ├── snapchat-mcp/      # Snapchat Ads
│   ├── amazon-dsp-mcp/    # Amazon DSP
│   ├── msads-mcp/         # Microsoft Ads
│   ├── dbm-mcp/           # Bid Manager (reporting)
│   ├── contract-schema/   # Shared library -- canonical annotation + response schemas
│   ├── contract-hash/     # Shared library -- canonical tool-definition hash
│   └── shared/            # Shared auth, telemetry, utilities
├── terraform/             # Infrastructure as Code
├── scripts/               # Deployment and dev automation
└── docs/                  # Documentation and guides

---

开发

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Type checking
pnpm run typecheck

# Lint
pnpm run lint

测试 MCP 工具

# Use MCP Inspector
npx @modelcontextprotocol/inspector packages/gads-mcp

# Or use curl
curl -X POST http://localhost:3004/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

技术栈

• 运行时：TypeScript 5.0+、Node.js 22 LTS、Hono（HTTP + MCP 传输）
• 验证：Zod 架构
• 基础设施：GCP Cloud Run、BigQuery、Pub/Sub、Secret Manager、Terraform
• 构建：Turborepo、pnpm 工作区、Docker

---

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/your-feature
3. 修改代码并编写测试
4. 运行测试：pnpm run test
5. 提交 Pull Request

另请参阅：CODE_OF_CONDUCT.md | SECURITY.md | ROADMAP.md

---

许可证

Apache License 2.0

---

支持

• 网站：cesteral.com -- 托管服务和商业功能
• 文档：docs/ 中的指南和架构说明
• GitHub Issues：报告错误或请求新功能
• 电子邮件：[email protected]