quantum-ads-mcp

CI CodeQL OpenSSF Scorecard Google Ads API Python MCP connectors mypy coverage License

The most complete open Model Context Protocol control plane for the Google marketing stack — 20 connectors, read + guarded write, Ed25519 signed audit, OAuth 2.1 multi-tenant.

Architecture · The 20 connectors · Install · Configure · Safety · Roadmap

A sovereign Google marketing-agency control plane over the Model Context Protocol: a shared core (multi-tenant auth, version resilience, a GAQL/query engine, a safety spine with a signed audit ledger) and 20 pluggable per-product connectors spanning the entire Google marketing stack. Built for an AI agent to operate that stack at full granularity, safely.

Status. The full connector surface is built and tested at the logic layer: read + guarded write across 20 products, every tool exercised by mocked tests (no live SDK needed). The per-product live SDK glue is isolated in sdk.py modules and smoke-gated (verified against real APIs with your own credentials, not in CI). Remaining for full production hardening: remote OAuth 2.1 transport + multi-tenant secret store + observability (see Roadmap). Read-only by default. Every "most X" claim here is meant to be verifiable.

Contents

Why · The 20 connectors · Architecture · Core · Install · Configure · Run · Safety & honest claims · Roadmap

Architecture

flowchart TD
    Client["MCP client (AI agent)"] -->|"stdio · or OAuth 2.1 HTTP (multi-tenant)"| Server["FastMCP server"]
    Server --> Core["Sovereign core: auth · version resilience · GAQL/query engine · safety spine (read-only default + Ed25519 signed audit) · registry / meta-tool"]
    Core --> C1["google_ads · ga4 · gtm · merchant"]
    Core --> C2["datamanager · searchconsole · youtube"]
    Core --> C3["dv360 · cm360 · sa360"]
    Core --> C4["bigquery · adh · looker · meridian"]
    Core --> C5["vertex · trends · gbp · language · workspace · recaptcha"]
    C1 -. "smoke-gated sdk.py" .-> G["Google APIs (Ads v24, GA4, GTM, Merchant, …)"]
    C4 -. "smoke-gated sdk.py" .-> G

Why this exists

Surveying June 2026: Google's official MCP is read-only (3 tools); the best open write-capable servers are pinned to sunsetting API versions, untested, single-product, or have no safety layer; the capable commercial ones are closed and remote-only. No open, self-hostable server is simultaneously complete across the stack, write-capable, safe, tested, version-resilient, and multi-product. Quantum ADS fills that gap.

The 20 connectors

Full tool catalog, backend keys, and required SDK packages: CONNECTORS.md.

Core (shared by every connector)

• Multi-tenant auth + secret store — credentials load from env / secret manager and never reach the LLM.
• Version resilience — pinned v24, sunset guard (days-until-sunset), unknown-enum tolerance (survives Google's monthly API releases and the 2026-06-10 DV360 Demand Gen rollout).
• Query engine — GAQL build / validate (single-FROM, no-OR, segment rules, 37-month cap) / stream / flatten, with quota token-buckets + exponential backoff. SA360 uses the same query shape.
• Safety spine — read-only by default; every mutation is guarded: validate_only preview → two-step confirm token → Ed25519 signed audit ledger. Consent-aware (Data Manager / Consent Mode v2) and cost-aware (BigQuery dry-run, $6.25/TiB).
• Connector registry + meta-tool discovery (list_capabilities, describe_tool) and env-based connector selection (QUANTUM_ADS_CONNECTORS) so the tool list stays focused.

Install

git clone https://github.com/Casius999/quantum-ads-mcp.git
cd quantum-ads-mcp
uv sync --extra dev
uv run pytest -m "not live"      # 250+ tests, no credentials needed

Per-connector live SDKs (e.g. google-analytics-data, google-api-python-client, google-cloud-bigquery) are installed only when you wire a connector's live backend — see CONNECTORS.md. The core + mocked test suite need none of them.

Configure

Credentials load from environment variables (no secrets on disk):

GOOGLE_ADS_USE_PROTO_PLUS=True
GOOGLE_ADS_API_VERSION=v24
GOOGLE_ADS_DEVELOPER_TOKEN=...
GOOGLE_ADS_CLIENT_ID=....apps.googleusercontent.com
GOOGLE_ADS_CLIENT_SECRET=...
GOOGLE_ADS_REFRESH_TOKEN=...
QUANTUM_ADS_READ_ONLY=true                 # writes refused until set to false
QUANTUM_ADS_CONNECTORS=google_ads,ga4,gtm  # optional: mount a subset (default: all 19)

Never commit .env, google-ads.yaml, or client_secret*.json — all gitignored, and gitleaks runs in CI. See SECURITY.md.

Run

python -m quantum_ads        # stdio MCP server

Wire it into your MCP client (Claude Desktop / VS Code) as a stdio server.

Safety & honest claims

Read-only by default; tokens never reach the model; zero secrets in the repo. CI runs lint, strict type-check, the full test suite (≥90% coverage gate), CodeQL, OpenSSF Scorecard, and gitleaks.

The defensible "most powerful" claim is coverage breadth + engineering rigor + safety + version resilience, each verifiable — not "record ad performance" (that depends on budget, creative, and Google's auction, not the server). Documentation states only what the test suite proves; the per-product live SDK calls are smoke-gated and labelled as such.

Roadmap (remaining for full production hardening)

Remote Streamable HTTP + OAuth 2.1/PKCE transport · multi-tenant secret store (per-client OAuth) · observability (structured logging + tracing) · live-API conformance suite · optional anchoring of the signed audit ledger.

License

MIT — see LICENSE.

— Julien Compain · NovaQuantiX