Metadata-Version: 2.4
Name: measure-paid-media-mcp
Version: 0.4.0
Summary: AI-powered Measurement Operations for paid media (Google Ads today; Meta, LinkedIn, TikTok, CM360 on the roadmap), over the Model Context Protocol.
Project-URL: Homepage, https://github.com/measure-mcp/measure-paid-media-mcp
Project-URL: Repository, https://github.com/measure-mcp/measure-paid-media-mcp
Author: Measure MCP contributors
License: Apache-2.0
License-File: LICENSE
Keywords: google-ads,mcp,measureops,model-context-protocol,paid-media,roas
Requires-Python: >=3.12
Requires-Dist: google-ads>=24.1.0
Requires-Dist: httpx>=0.27
Requires-Dist: measure-sdk<0.3,>=0.2
Provides-Extra: cm360
Requires-Dist: google-api-python-client>=2.100.0; extra == 'cm360'
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: microsoft
Requires-Dist: bingads>=13.0.0; extra == 'microsoft'
Description-Content-Type: text/markdown

<div align="center">

# 📈 Measure Paid Media MCP

**AI-powered Measurement Operations for paid media, over the
[Model Context Protocol](https://modelcontextprotocol.io).**

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](https://github.com/measure-mcp) ·
built on **[measure-sdk](https://github.com/measure-mcp/measure-sdk)**.

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
[![SDK](https://img.shields.io/badge/measure--sdk-%3E%3D0.1%2C%3C0.2-blue.svg)](https://github.com/measure-mcp/measure-sdk)

</div>

---

## 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.

```text
"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`](https://github.com/measure-mcp/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

```bash
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:

```bash
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`](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)

```text
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`](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](SECURITY.md).

## Develop

```bash
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](CHANGELOG.md)** · **[ROADMAP.md](ROADMAP.md)** ·
**[SECURITY.md](SECURITY.md)** · **[CONTRIBUTING.md](CONTRIBUTING.md)** ·
**[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**.

## License

[Apache-2.0](LICENSE). Contributions welcome.
