gadschain

GadsChain

连接 Google Ads 账户与营销决策的 AI 层。

经过实战检验。 六种工具覆盖日常运营流程——列出广告系列、审核搜索词、调整预算、暂停／启用广告系列，以及整理否定关键词。所有响应均为严格的 Pydantic 模型。原始 protobuf 不会传递给 Agent。

☁️ 准备投入生产？

开源服务可在本地使用你自己的 API 密钥运行。 如需支持多账户故障转移、SLA 保证 和 webhook 提醒的托管基础设施——加入托管云候补名单。

问题

原始 Google Ads API 会返回数千行数据。一种糟糕的广告系列结构就可能悄无声息地消耗预算。GadsChain 会读取、清理并处理你的广告数据，避免浪费不断累积。

安装

git clone https://github.com/SnipMCP/gadschain.git
cd gadschain
pip install -e ".[dev]"
cp .env.example .env

也可以使用 Docker：

docker-compose up --build

配置

GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
GOOGLE_ADS_CLIENT_ID=your_oauth_client_id_here
GOOGLE_ADS_CLIENT_SECRET=your_oauth_client_secret_here
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token_here
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890   # MCC (manager), digits only
GOOGLE_ADS_CUSTOMER_ID=1234567890         # default operating account
GOOGLE_ADS_API_VERSION=v24
LOG_LEVEL=INFO

用法

以下是三个可发送给 Claude（或任何兼容 MCP 的 Agent）的示例提示词：

1. Use get_campaigns to show me which campaigns are bleeding budget this month
2. Run get_search_terms for the last 30 days and tell me which queries are wasting spend
3. Add "free", "cheap", "jobs" as negative keywords to campaign 12345

在两个终端中运行

# Tab 1 — start the MCP server
python -m gadschain.server

# Tab 2 — call a tool from a Python shell or your MCP client
# Tool signatures:
#   get_campaigns(customer_id=None)
#   get_search_terms(customer_id=None, days=30, campaign_id=None)
#   update_budget(campaign_id, new_budget_dollars, customer_id=None)
#   pause_campaign(campaign_id, customer_id=None)
#   enable_campaign(campaign_id, customer_id=None)
#   add_negative_keywords(campaign_id, keywords, match_type="BROAD", customer_id=None)

工作原理

原始 Google Ads 输出与模型之间的三个处理层：

Google Ads API → [Fetch] → [Transform] → [Act] → MCP Tool → AI Agent
                  GAQL      micros→$       safe
                  queries   enum→str       mutations
                            CTR→%          shared-budget guard

• 获取：使用有针对性的 GAQL 查询，只查询日常运营流程实际需要的列。没有 SELECT *，也不会遇到 protobuf 分页陷阱。
• 转换：将货币微单位换算为美元，将 CTR 换算为百分比，将枚举值转换为易读文本；对每个嵌套属性的查找都会容错处理缺失字段，不会导致崩溃。
• 执行：所有变更操作都经过防护规则——状态变更会阻止 REMOVED，拒绝共享预算（shared_budget_refused），并在调用任何变更操作前验证匹配类型。Agent 不会收到异常，而是会收到结构化的 {"error": ..., "message": ...}，以便进行推理。

来自真实 Franka Pizzeria 账户的数据（28 天窗口期）

RAW GOOGLE ADS PAYLOAD          GADSCHAIN OUTPUT
─────────────────────────────────────────────────
Impressions:    3,389           Spend (28d):      $51.41
Clicks:         163             Conversions:      3 ($17.14 each)
CTR:            4.81%           Conv. rate:       1.84%
Cost/click:     $0.32 avg       Surface:          Display Network waste
                                                  identified on Fridays
                                                  ($0.11 CPC vs $0.44 avg)

在读取一个真实账户时，GadsChain 发现，28 天内花费了 $51.41，获得 3 次转化，每次转化成本为 $17.14——转化率为 1.84%，隐藏在纸面上看起来不错的 4.81% CTR 之中。展示广告网络才是悄无声息的罪魁祸首：周五点击的平均 CPC 为 $0.11，而搜索广告的平均 CPC 为 $0.44——廉价的垃圾流量推高了 CTR，却没有带来任何转化。Agent 能发现这一点，是因为经过转换的数据载荷让渠道归因一目了然，而非埋藏在 protobuf 中。

路线图

• 托管云版本（托管式、多租户、webhook 提醒）
• 第二阶段：ChatGPT REST 适配层（基于同一组六种工具的 FastAPI 接口）
• 出价策略调整工具（目标 CPA、目标 ROAS）
• 每次转化成本偏移异常提醒

贡献

欢迎提交 PR。提交前请运行 pytest。