Which integrations are available for this server?

Provides tools for retrieving Google Ads performance data, campaign settings, and change history, enabling live daily-dashboard workflows. Provides tools for retrieving Meta (Facebook) Ads performance data and campaign settings, enabling live daily-dashboard workflows.

How do I use ads-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ads-mcp-server show Google Ads report for last week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

ads-mcp-server

by jmacaggi-gfm

Overview Schema Source Related Servers Discussions Admin

Python

Local

ads-mcp-server

Local MCP server exposing Google Ads + Meta Marketing performance data, campaign settings, and change history to Claude (Cowork) for live daily-dashboard workflows.

What it does

Three tools registered with MCP:

Tool	Purpose
`get_google_ads_report(date_range, breakdown)`	Performance + diagnostics + 56-day series + WoW + 8-week DoW comparisons + campaign settings + change history
`get_meta_ads_report(date_range, breakdown)`	Same shape as Google. Conversions filtered to `META_CONVERSION_EVENT_NAME`
`get_campaign_settings(platform)`	Settings + change history for `google` / `meta` / `both`

Architecture: pull ad×day raw once per platform per hour, cache to parquet, derive every aggregation in pandas. No API call per breakdown.

Related MCP server: Google Ads MCP Server

Prerequisites

macOS / Linux
Python 3.13 (via pyenv recommended)
uv package manager: brew install uv
Google Ads API access — see Google Ads API getting started
Meta Marketing API access — see Marketing API getting started

Credential setup links

Credential	Where to get it
`GOOGLE_ADS_DEVELOPER_TOKEN`	Google Ads UI → Tools → API Center
`GOOGLE_ADS_CLIENT_ID` / `CLIENT_SECRET`	https://console.cloud.google.com → OAuth 2.0 client (Desktop app)
`GOOGLE_ADS_REFRESH_TOKEN`	Run `python -m google.ads.googleads.examples.authentication.generate_user_credentials` after installing `google-ads`
`GOOGLE_ADS_CUSTOMER_IDS`	Comma-separated, no dashes. Find in Google Ads UI top-right
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	MCC manager account ID, no dashes
`META_APP_ID` / `META_APP_SECRET`	https://developers.facebook.com → My Apps → Settings → Basic
`META_ACCESS_TOKEN`	https://business.facebook.com → Business Settings → System Users → Generate New Token (long-lived, with `ads_read`)
`META_AD_ACCOUNT_ID`	Meta Ads Manager → top-left account picker. Format: `act_XXXXXXXXX`

Install

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

uv creates .venv/ and installs all deps pinned in pyproject.toml.

Configure credentials

Two options:

Option A — point at existing .env (recommended if you already have keys in ~/marketing-ds/decision_science/.env):

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

Option B — local .env:

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

Required keys are listed in .env.example with comments explaining each.

Run

Locally for testing:

uv run ads-mcp-server

The server speaks MCP over stdio — Cowork (or any MCP client) spawns it on demand.

Connect to Claude (Cowork)

Add this block to ~/.claude/claude_desktop_config.json (create if missing):

{
  "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"
      }
    }
  }
}

Restart Claude/Cowork. Tools get_google_ads_report, get_meta_ads_report, get_campaign_settings should appear.

No background daemon required — Cowork starts/stops the process per session.

Daily pre-warm (recommended for live dashboard)

Cache validity rule: a cache is fresh if it contains yesterday's date. Refreshes once per day. The first user query of the day triggers the refresh — and a 56-day pull on a large account can take 1-3 minutes.

To avoid that wait, schedule a pre-warm at 6am via macOS launchd:

# 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

What it does each morning at 6am:

Pulls Google Ads perf 56d, settings, change_event 29d → cache
(Meta currently disabled — see "Meta status" below)
Writes refresh stamp cache/google_lastrefresh.txt = today

By the time you open Cowork, Google data is hot. Tool calls return in <1s.

To uninstall:

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

Meta status (as of 2026-05-07)

Meta tools (get_meta_ads_report, get_campaign_settings(platform="meta"|"both")) are structurally complete but not yet verified end-to-end.

What works:

Performance pull is chunked into 7-day windows (avoids the Service temporarily unavailable / subcode 1504044 "result too large" error)
Ad-level data is split: level=campaign for the 56-day series, level=ad for yesterday-only (avoids 5-minute pagination)
AdSet pull is filtered to effective_status IN [ACTIVE, PAUSED] (avoids paginating thousands of archived ad sets)

What blocked us:

After the first big perf chunked pull, the AdSet pull hit Meta's hourly rate limit (code 17, subcode 2446079: "User request limit reached"). Cooldown is typically 10-60 minutes.

To re-test tomorrow morning (after quota resets):

# 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

If Meta keeps rate-limiting, fallback options (not yet implemented):

Async report runs (async=True) for the perf pull
Tighter effective_status filter (ACTIVE only, drop paused)

If you prefer a long-running background process (optional, not required for Cowork): use nohup uv run ads-mcp-server > /tmp/ads-mcp.log 2>&1 & or a launchd plist.

Optional: CSV override (skip the API)

Google Ads UI exports CSV reports without API quota limits. Drop a CSV into cache/external/ to override the API pull:

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

If a matching CSV exists AND is newer than the parquet cache, the server loads it instead of calling the API. The response sets metadata.data_source = "csv_override" so Cowork knows.

CSV column schema must match the parquet (see src/ads_mcp_server/google_ads.py and meta_ads.py for column names: date, campaign_id, campaign_name, ad_id, ad_name, spend, impressions, clicks, conversions, ...).

Test

uv run pytest -v

All tests are mock-based — no network calls. Covers:

classify_campaign Brand/Non-Brand/Other
diagnose 5-state classifier
8-week same-DoW selector picks the right 8 dates
WoW delta + zero-division
actions[] filter for Meta
Snapshot diff including null-old-value and pruning
Missing creds returns clean error (no exception)

Logs

Every API call and error is logged to logs/YYYY-MM-DD.log (one file per day).

Troubleshooting

google-ads install fails: ensure Python 3.13 (uv python pin 3.13) and pip install grpcio works on your system. On Apple Silicon: arch -arm64 uv sync.
Meta token expired: regenerate the system user token in Business Settings; long-lived tokens last 60 days.
Tool not appearing in Cowork: check ~/Library/Logs/Claude/mcp*.log for spawn errors. Confirm uv is in PATH for the GUI process (you may need a full path: which uv).
Cache stale: delete cache/*.parquet to force fresh pull.

File map

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

Name	Required	Description	Default
`platform`	Yes

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

Name	Required	Description
`date_range`	Yes
`breakdown`	Yes
`include_campaign_settings`	No	If 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

Name	Required	Description	Default
`date_range`	Yes
`breakdown`	Yes

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.

3 tool updatesv0.1.0May 8, 2026
- First observedget_campaign_settings
- First observedget_google_ads_report
- First observedget_meta_ads_report

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0

Scored 2026-05-08 03:10 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

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp-serverOAuth
co.flyweel
Access Google & Meta Ads data via AI. Analyse campaign performance in seconds.
Marketing Search Data Platforms
2
AttachéOAuth
studio.attache
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Marketing Customer Data Platforms
1
LoomaScale AdsOAuth
com.loomascale
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
Marketing Social Media App Automation
1
syncmetricsOAuth
io.github.shamsuzzaman1
Ask Claude about your ads: Meta, Google, TikTok, LinkedIn, GA4 & Shopify. No AI credits.
Marketing E-commerce & Retail
2

Related MCP Servers

Google Ads MCP Server
Marketing Data Visualization
CoraCote
F
license
Not graded
quality
D
maintenance
Enables natural language access to Google Ads campaigns, accounts, and performance metrics via Claude, with tools for managing ad groups, keywords, budgets, and visualizing data.
Updated 3 months ago (2026-06-17 20:01 UTC)
1
-
Google Ads MCP Server
Marketing Search
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.
Updated 7 months ago (2026-02-16 18:11 UTC)
83
2
MIT
mcp-marketing-analytics
Marketing Search
christophertanenso
F
license
A
quality
D
maintenance
Enables natural language querying of Google Analytics 4, Google Search Console, Meta Ads, and Google Ads data through Claude.
Updated 7 months ago (2026-02-26 07:04 UTC)
23
-
OQVA Marketing MCPofficial
Marketing Social Media
oqva-digital
A
license
A
quality
A
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.
Updated 24 days ago (2026-08-19 16:23 UTC)
35
Apache 2.0

ads-mcp-server

What it does

Prerequisites

Credential setup links

Install

Configure credentials

Run

Connect to Claude (Cowork)

Daily pre-warm (recommended for live dashboard)

Meta status (as of 2026-05-07)

Optional: CSV override (skip the API)

Test

Logs

Troubleshooting

File map

Available Tools

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Google Ads MCP Server

Google Ads MCP Server

mcp-marketing-analytics

OQVA Marketing MCPofficial