measure-paid-media-mcp 0.4.0

AI-powered Measurement Operations for paid media (Google Ads today; Meta, LinkedIn, TikTok, CM360 on the roadmap), over the Model Context Protocol.

📈 Measure Paid Media MCP

AI-powered Measurement Operations for paid media, over the Model Context Protocol.

Audit · analyse · monitor your paid-media campaigns in natural language, from Claude, ChatGPT, Codex, Gemini or any MCP client.

A product of the Measure AI ecosystem · built on measure-sdk.

---

What is Measure Paid Media MCP?

An open-source MCP server that lets an AI assistant audit campaigns, validate tracking, compare platforms and recommend optimisations across your paid-media stack — read-only and safe by design. It is part of the Measure AI ecosystem and depends on only measure-sdk (shared auth, config, logging and domain models); it never depends on another MCP.

"Audit all active campaigns from the last 30 days."
"Find campaigns with spend but no conversions."
"Compare Google Ads and Meta Ads ROAS for the last 14 days."
"Check if my conversion tracking pixels are healthy."
"Generate a paid media performance report by platform."
"What optimizations should I make this week?"

Relationship to Measure SDK

This product is a thin, focused layer on top of measure-sdk:

Provided by measure-sdk	Provided by this repo
OAuth, sessions, credential storage	Paid-media connectors (Google Ads, …)
Config, logging, HTTP, retry, rate limiting	Audit / tracking / reporting / recommendation engines
MCP utilities, base CLI (measure login)	MCP server + paid-media tools
Shared domain models & enums	Normalised Campaign / TrackingSignal

Shared result types — AuditFinding, Recommendation, Report, Metric, HealthScore, Connection, ValidationResult — all come from the SDK and are never redefined here.

Install

pip install measure-paid-media-mcp     # pulls measure-sdk automatically
measure login                          # Google OAuth (from the SDK)
measure doctor                         # what's connected
measure-paid-media                     # start the MCP server (stdio)

Configuration is optional and non-secret (defaults, thresholds, feature flags). For Google Ads, set MEASURE_ADS_DEVELOPER_TOKEN and MEASURE_ADS_CUSTOMER_ID. Credentials are never stored in .env.

Try it instantly (demo mode)

No account? Explore every tool with realistic sample data — no credentials:

MEASURE_PM_DEMO=true measure-paid-media

Demo mode serves sample Google Ads + Meta campaigns and tracking signals, so audit_campaigns, get_cross_channel_performance, generate_optimization_recommendations, etc. all return rich output. It is clearly labelled as DEMO in check_platform_health and never hits a live API.

Connect to Claude Desktop

See examples/claude_desktop/config.json.

Supported platforms

Phase	Platforms
1	Google Ads ✅ · Meta Ads ✅ · cross-channel reporting · campaign & tracking audit
2	LinkedIn Ads ✅ · TikTok Ads ✅ · Microsoft Ads ✅ (enable via flags)
3	CM360 ✅ · Floodlight 🟡 · advanced recommendations · alerting automation

Adding a platform is a new connector under connectors/ implementing one Protocol — no engine or tool changes required.

MCP tools (MVP)

Group	Tools
Connections	list_connected_platforms, check_platform_health
Campaign audit	audit_campaigns, find_wasted_spend, find_campaigns_without_conversions, find_low_roas_campaigns, find_high_cpa_campaigns
Tracking audit	audit_tracking, check_conversion_pixels, find_missing_conversion_events
Reporting	get_cross_channel_performance, compare_platform_performance, generate_paid_media_report
Recommendations	generate_optimization_recommendations
Alerts	evaluate_alert, send_notification (console / Slack / Teams / Discord)

Architecture (Clean Architecture)

src/measure_paid_media/
├── core/          # domain: Campaign/TrackingSignal models, enums, connector PORT
├── config/        # settings (extends SDK CoreSettings; optional, non-secret)
├── connectors/    # infrastructure: one vertical per platform (implements the port)
│   ├── google_ads/  meta_ads/  linkedin_ads/  tiktok_ads/  microsoft_ads/  cm360/
├── engines/       # application: pure use cases → SDK domain models
│   ├── audit/  tracking/  reporting/  recommendations/  alerts/
├── services/      # orchestration: connectors → engines (the tools call this)
├── validators/    # input validation → SDK ValidationResult
├── mcp/           # interface: server.py + tools/ (one module per group)
└── cli/           # interface: the measure-paid-media entry point

Dependencies point inward: mcp/cli → services → engines → core; connectors implement core's port. Engines are pure and platform-agnostic, so the same audit rules run on every platform. See docs/architecture/overview.md.

Security & disclaimer

This MCP is read-only: it audits, analyses and recommends. It never modifies, pauses or rebudgets campaigns. Any future write capability will require preview → dry-run → explicit user confirmation → audit log, gated by the SDK's permission policy. See SECURITY.md.

Develop

git clone https://github.com/measure-mcp/measure-paid-media-mcp.git
cd measure-paid-media-mcp
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ../measure-sdk          # or the published measure-sdk
pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy . && pytest

Ecosystem

measure-sdk	Shared core: domain models, enums, Health Score, infra.
measure-analytics-mcp	GA4, GTM, BigQuery, Consent, Server-Side, Data Quality, Alerts.
measure-paid-media-mcp	This product.

See CHANGELOG.md · ROADMAP.md · SECURITY.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md.

License

Apache-2.0. Contributions welcome.