ads-mcp-server

本地 MCP 服务器，将 Google Ads + Meta Marketing 的性能数据、广告系列设置及变更历史暴露给 Claude (Cowork)，以实现实时的日常仪表板工作流。

功能概述

MCP 注册了三个工具：

架构：每个平台每小时拉取一次原始的“广告×天”数据，缓存为 parquet，并在 pandas 中派生所有聚合数据。无需针对每个细分维度进行 API 调用。

Related MCP server: Google Ads MCP Server

前置要求

• macOS / Linux

• Python 3.13 (推荐使用 pyenv)

• uv 包管理器：brew install uv

• Google Ads API 访问权限 — 参见 Google Ads API 入门

• Meta Marketing API 访问权限 — 参见 Marketing API 入门

凭据设置链接

安装

cd ~/marketing-ds/ads-mcp-server
uv sync --extra dev

uv 会创建 .venv/ 并安装 pyproject.toml 中锁定的所有依赖项。

配置凭据

两种选项：

选项 A — 指向现有的 .env (如果您已经在 ~/marketing-ds/decision_science/.env 中拥有密钥，推荐此方式)：

export ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env

选项 B — 本地 .env：

cp .env.example .env
# fill in the blanks

所需密钥列在 .env.example 中，并附有解释说明。

运行

本地测试：

uv run ads-mcp-server

服务器通过 stdio 进行 MCP 通信 — Cowork（或任何 MCP 客户端）会按需启动它。

连接到 Claude (Cowork)

将此块添加到 ~/.claude/claude_desktop_config.json (如果不存在则创建)：

{
  "mcpServers": {
    "ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jmacaggi/marketing-ds/ads-mcp-server",
        "run",
        "ads-mcp-server"
      ],
      "env": {
        "ADS_MCP_ENV_FILE": "/Users/jmacaggi/marketing-ds/decision_science/.env"
      }
    }
  }
}

重启 Claude/Cowork。工具 get_google_ads_report、get_meta_ads_report、get_campaign_settings 应该会出现。

无需后台守护进程 — Cowork 会在每个会话中启动/停止该进程。

每日预热（推荐用于实时仪表板）

缓存有效性规则：如果缓存包含昨天的日期，则视为新鲜。每天刷新一次。当天的第一个用户查询会触发刷新 — 对于大型账户，拉取 56 天的数据可能需要 1-3 分钟。

为避免等待，可通过 macOS launchd 在早上 6 点安排预热：

# Install
cp /Users/jmacaggi/marketing-ds/ads-mcp-server/launchd/com.jmacaggi.adsmcp.prewarm.plist \
   ~/Library/LaunchAgents/

launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Verify it's scheduled
launchctl list | grep adsmcp

# Trigger immediately (test)
launchctl start com.jmacaggi.adsmcp.prewarm

# Logs
tail -f ~/marketing-ds/ads-mcp-server/logs/prewarm.stdout.log
tail -f ~/marketing-ds/ads-mcp-server/logs/$(date +%Y-%m-%d).log

每天早上 6 点执行的操作：

1. 拉取 Google Ads 56 天性能、设置、29 天变更事件 → 缓存

2. (Meta 目前已禁用 — 参见下方的“Meta 状态”)

3. 写入刷新时间戳 cache/google_lastrefresh.txt = 今天

当您打开 Cowork 时，Google 数据已准备就绪。工具调用可在 1 秒内返回。

卸载：

launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
rm ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

Meta 状态 (截至 2026-05-07)

Meta 工具 (get_meta_ads_report, get_campaign_settings(platform="meta"|"both")) 结构完整，但尚未进行端到端验证。

已实现功能：

• 性能拉取分块为 7 天窗口（避免 Service temporarily unavailable / subcode 1504044 “结果过大”错误）

• 广告层级数据拆分：56 天序列使用 level=campaign，仅昨日数据使用 level=ad（避免 5 分钟的分页限制）

• 广告系列组 (AdSet) 拉取过滤为 effective_status IN [ACTIVE, PAUSED]（避免对数千个已归档的广告系列组进行分页）

阻碍因素：

• 在首次大规模性能分块拉取后，AdSet 拉取触及了 Meta 的每小时速率限制（code 17，子代码 2446079：“达到用户请求限制”）。冷却时间通常为 10-60 分钟。

明天早上（配额重置后）重新测试：

# Remove --skip-meta from the launchd plist to enable Meta in pre-warm
sed -i '' '/<string>--skip-meta<\/string>/d' \
   ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl unload ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist
launchctl load ~/Library/LaunchAgents/com.jmacaggi.adsmcp.prewarm.plist

# Or run manually
ADS_MCP_ENV_FILE=/Users/jmacaggi/marketing-ds/decision_science/.env \
   uv run python scripts/prewarm.py

如果 Meta 继续限制速率，备选方案（尚未实现）：

• 性能拉取使用异步报告运行 (async=True)

• 更严格的 effective_status 过滤器（仅限 ACTIVE，丢弃已暂停的）

如果您更喜欢长时间运行的后台进程（可选，Cowork 不需要）：使用 nohup uv run ads-mcp-server > /tmp/ads-mcp.log 2>&1 & 或 launchd plist。

可选：CSV 覆盖（跳过 API）

Google Ads UI 导出的 CSV 报告不受 API 配额限制。将 CSV 放入 cache/external/ 即可覆盖 API 拉取：

cache/external/google_2026-05-07.csv
cache/external/meta_2026-05-07.csv

如果存在匹配的 CSV 且其更新时间晚于 parquet 缓存，服务器将加载该 CSV 而不是调用 API。响应会将 metadata.data_source 设置为 "csv_override"，以便 Cowork 知晓。

CSV 列架构必须与 parquet 匹配（列名请参见 src/ads_mcp_server/google_ads.py 和 meta_ads.py：date, campaign_id, campaign_name, ad_id, ad_name, spend, impressions, clicks, conversions, ...）。

测试

uv run pytest -v

所有测试均基于模拟 — 无网络调用。涵盖：

• classify_campaign 品牌/非品牌/其他

• diagnose 5 状态分类器

• 8 周同星期几选择器选取正确的 8 个日期

• 周环比增量 + 除以零处理

• Meta 的 actions[] 过滤器

• 快照差异（包括空旧值和修剪）

• 凭据缺失时返回清晰错误（无异常）

日志

每次 API 调用和错误都会记录到 logs/YYYY-MM-DD.log（每天一个文件）。

故障排除

• google-ads 安装失败：确保 Python 3.13 (uv python pin 3.13) 且 pip install grpcio 在您的系统上可用。在 Apple Silicon 上：arch -arm64 uv sync。

• Meta 令牌过期：在企业设置中重新生成系统用户令牌；长期令牌有效期为 60 天。

• 工具未在 Cowork 中显示：检查 ~/Library/Logs/Claude/mcp*.log 查看启动错误。确认 uv 在 GUI 进程的 PATH 中（您可能需要使用完整路径：which uv）。

• 缓存陈旧：删除 cache/*.parquet 以强制刷新。

文件映射

src/ads_mcp_server/
  server.py        # MCP entry + tool handlers
  config.py        # env loading, validates creds
  google_ads.py    # 3 GAQL queries: perf, settings, change_event
  meta_ads.py      # Insights + AdSet pull
  snapshots.py     # Meta snapshot diff (Meta has no reliable change API)
  cache.py         # parquet + CSV override
  aggregate.py     # all pandas math
  classify.py      # Brand/NB/Other
  diagnose.py      # 5-state diagnosis
  date_ranges.py   # window resolution + 8wk DoW
  retry.py         # exponential backoff
  logging_setup.py # daily file logs
  schema.py        # response shape constants