Skip to main content
Glama
deenesjakoruzh
jmacaggi-gfm

ads-mcp-server

by jmacaggi-gfm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

ads-mcp-server

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

功能概述

MCP 注册了三个工具：

工具

用途

get_google_ads_report(date_range, breakdown)

性能 + 诊断 + 56 天序列 + 周环比 (WoW) + 8 周同星期几 (DoW) 对比 + 广告系列设置 + 变更历史

get_meta_ads_report(date_range, breakdown)

与 Google 格式相同。转化数据过滤为 META_CONVERSION_EVENT_NAME

get_campaign_settings(platform)

google / meta / both 的设置 + 变更历史

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

Related MCP server: mcp-marketing-analytics

前置要求

凭据设置链接

凭据

获取位置

GOOGLE_ADS_DEVELOPER_TOKEN

Google Ads UI → 工具 → API 中心

GOOGLE_ADS_CLIENT_ID / CLIENT_SECRET

https://console.cloud.google.com → OAuth 2.0 客户端 (桌面应用)

GOOGLE_ADS_REFRESH_TOKEN

安装 google-ads 后运行 python -m google.ads.googleads.examples.authentication.generate_user_credentials

GOOGLE_ADS_CUSTOMER_IDS

逗号分隔，无连字符。在 Google Ads UI 右上角查找

GOOGLE_ADS_LOGIN_CUSTOMER_ID

MCC 管理员账户 ID，无连字符

META_APP_ID / META_APP_SECRET

https://developers.facebook.com → 我的应用 → 设置 → 基本

META_ACCESS_TOKEN

https://business.facebook.com → 企业设置 → 系统用户 → 生成新令牌 (长期有效，需包含 ads_read)

META_AD_ACCOUNT_ID

Meta 广告管理工具 → 左上角账户选择器。格式：act_XXXXXXXXX

安装

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

Available Tools

3 tools
get_campaign_settingsC

Current campaign settings + 56-day change history per platform.

ParametersJSON Schema
NameRequiredDescriptionDefault
platformYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavioral traits. It discloses that the tool returns both settings and a 56-day history, but does not indicate whether it is read-only, any authentication needs, rate limits, or what triggers destructive actions. The behavior is partially described but lacks completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, making it very concise, but it omits important details such as parameter semantics and usage context. Conciseness is achieved at the expense of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is insufficient. It does not explain the output structure, whether the data is aggregated per platform, or provide examples. The lack of detail makes it hard for an AI agent to fully understand the tool's capabilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter 'platform' with enum values, but the description does not explain the parameter's meaning beyond 'per platform'. It fails to clarify what 'both' implies or how the parameter affects the output. With 0% schema description coverage, the description adds no value over the schema itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves 'current campaign settings + 56-day change history per platform', which is a specific verb+resource. However, it does not explicitly differentiate itself from sibling tools like get_google_ads_report or get_meta_ads_report, which are focused on ads reports rather than settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as get_google_ads_report or get_meta_ads_report. It does not mention exclusion criteria or context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_google_ads_reportA

Pull Google Ads performance. Returns account totals, campaign-type breakdown, top-50 per-ad rows with diagnosis, 56-day daily series, and WoW + 8-week DoW comparisons. Set include_campaign_settings=True to also return per-campaign settings (target CPA, daily budget, diagnosis, utilization) for ENABLED campaigns only.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_rangeYes
breakdownYes
include_campaign_settingsNoIf true, attach campaign_settings list to the response. Defaults to false to keep payload small.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description details return components and the conditional behavior of include_campaign_settings (only for ENABLED campaigns).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, no fluff, front-loaded with purpose and outputs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description covers essential behavioral and parameter details despite lack of output schema; minor gaps in rate limits or authentication info.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (33%), but the description adds meaning to parameters by linking them to return elements (e.g., 'campaign-type breakdown' for breakdown enum).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Pull Google Ads performance' and lists specific outputs, distinguishing it from siblings like get_meta_ads_report and get_campaign_settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use for Google Ads performance but does not explicitly guide when to use this tool over siblings or provide exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_meta_ads_reportB

Pull Meta Ads performance. Same shape as get_google_ads_report. Conversions filtered to META_CONVERSION_EVENT_NAME.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_rangeYes
breakdownYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only mentions the output shape similarity and a conversion filter, but lacks details on side effects, rate limits, authentication needs, or other behavioral traits. This is minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two short sentences, each providing distinct value. It front-loads the key information and avoids fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should explain the report contents. It mentions a conversion filter but does not list other metrics or describe the full structure. Relying on the shape of get_google_ads_report is insufficient without that tool's description being present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should add meaning to parameters. It does not explain the 'date_range' or 'breakdown' parameters beyond their enum values, which are self-explanatory but not enriched. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The name and description clearly indicate this tool retrieves Meta Ads performance data. The verb 'Pull' is specific, and the description explicitly states it is analogous to get_google_ads_report, which distinguishes it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by comparing to get_google_ads_report, but does not provide explicit guidance on when to use this tool versus alternatives or any prerequisites. No exclusions or when-not-to-use information is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_campaign_settings
    • First observedget_google_ads_report
    • First observedget_meta_ads_report
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct area: campaign settings, Google Ads performance, and Meta Ads performance. No overlap; descriptions clearly differentiate them.

Naming Consistency5/5

All tool names follow a consistent 'get_' prefix with the specific resource (campaign_settings, google_ads_report, meta_ads_report). Consistent snake_case pattern.

Tool Count4/5

Three tools is minimal but appropriate for a focused ads reporting and settings retrieval server. Could be expanded but current count is reasonable for the stated purpose.

Completeness2/5

Only read operations are exposed; no create, update, or delete tools for campaigns or ads. Significant gaps for a full ads management workflow.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Google Ads MCP Server

    jgdeutsch
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides access to Google Ads API for comprehensive campaign analytics, enabling conversational ad performance analysis with Claude Code.
    25 npm
    2
    MIT
  • OQVA Marketing MCP by oqva-digital

    OQVA Marketing MCPofficial

    oqva-digital
    A
    license
    A
    quality
    B
    maintenance
    Connect Claude to your marketing data from Google and Meta, enabling read and write operations on Search Console, Analytics, Tag Manager, Business Profile, and Meta platforms.
    35
    Apache 2.0