Ads Analytics MCP

An open-source Model Context Protocol (MCP) server that gives an AI assistant (Claude Desktop, Claude Code, or any MCP client) read access to campaign performance data from three ad platforms:

• Google Ads

• Meta Ads (Facebook / Instagram)

• TikTok Ads

It exposes campaign, hourly, ad-level, and account-level insight tools. All data is fetched live from each platform's official API using credentials you supply. Nothing is bundled, cached to a database, or sent anywhere else.

On top of the raw tools, the repository ships a Claude intelligence layer: skills and subagents that turn those tools into opinionated, Spain-specific audits and recommendations (see The Claude intelligence layer).

No credentials are included in this repository. Copy the example files and fill in your own. See Configuration.

Table of contents

• How it fits together

• Features

• Available tools

• Requirements

• Installation & build

• Configuration

• Connecting to an MCP client

• The Claude intelligence layer

  • Skills

  • Subagents

  • Reference knowledge base

  • How skills, agents, and tools play together

• Development

• Architecture

• Security

• License

Related MCP server: Meta Marketing API MCP Server

How it fits together

There are two distinct layers in this repo:

┌──────────────────────────────────────────────────────────────┐
│  Claude intelligence layer  (.claude/)                        │
│                                                               │
│   Skills            Subagents           References            │
│   google-ads   ──►  audit-google   ──►  benchmarks-spain.md   │
│   meta-ads     ──►  audit-meta          compliance-eu-spain.md│
│   tiktok-ads   ──►  audit-tiktok        platform-specs.md     │
│   ads-budget-review ─► audit-budget                           │
│   ads-pacing-monitor   business-analyst                       │
│   ads-strategy-plan                                           │
│   ab-test-design                                              │
│   competitor-teardown                                         │
└───────────────────────────────┬──────────────────────────────┘
                                 │ calls MCP tools
                                 ▼
┌──────────────────────────────────────────────────────────────┐
│  MCP server  (src/ → dist/)                                   │
│                                                               │
│   tools/  ──►  services/  ──►  adapters/  ──►  Platform APIs  │
│   (16 read-only tools)                       Google / Meta /  │
│                                              TikTok           │
└──────────────────────────────────────────────────────────────┘

• The MCP server (src/) is plain, provider-agnostic infrastructure: 16 read-only tools that any MCP client can call. It has no opinions. It returns normalized metrics.

• The Claude layer (.claude/) is optional and Claude-specific. Skills are the entry points users trigger by phrase; they pull data with the tools and delegate deep work to subagents; subagents score against the reference benchmarks and write reports. You can run the server with no Claude layer at all and still use every tool.

Features

• 🔌 Live API access to Google Ads, Meta Marketing API, and TikTok Marketing API

• 📊 Campaign performance, hourly breakdowns, ad-level, search terms, keywords, impression share

• 🧠 Account-level insight tools: opportunity score, auction rankings, anomaly signals

• 👥 Multi-account: configure as many accounts as you like, one JSON file each

• 🔒 Secrets stay local. .env + clients/*.json are git-ignored by default

• 🤖 Optional Claude skills + subagents for Spain-specific audits and budget strategy

Available tools

All 16 tools are read-only. Every metric is normalized into a common shape (spend, impressions, clicks, CTR, CPC, CPM, conversions, CPA, conversion value, ROAS) before it leaves the server, so an agent sees the same vocabulary across platforms.

Requirements

• Node.js >= 20

• API access on each platform you want to use:

  • Google Ads: a Google Cloud OAuth app + a Google Ads API developer token

  • Meta: a Marketing API app and a (preferably long-lived System User) access token with ads_read

  • TikTok: a TikTok Marketing API app

Installation & build

git clone <your-fork-url>
cd ads-analytics-mcp
npm install      # install dependencies
npm run build    # compile TypeScript src/ → dist/

npm run build runs tsc and emits the runnable server to dist/index.js. That compiled file is what every MCP client launches. Always rebuild after changing anything under src/.

Verify the build booted correctly (lists all tools over stdio without needing credentials):

npm start        # node dist/index.js, should log "server connected via stdio"

The server starts even with zero accounts configured (it just exposes list_clients returning an empty list). Credentials are only needed when you actually call a platform tool.

Configuration

Credentials are split in two:

1. App-level credentials → .env (your OAuth apps / developer tokens)

2. Account-level credentials → clients/<id>.json (per-account IDs + tokens)

1. App-level .env

cp .env.example .env

Fill in your Google Ads OAuth app + developer token, and (if using TikTok) your TikTok app id/secret. See the comments in .env.example.

2. Account files

cp clients/_example.json clients/my-account.json

Edit it with the account IDs and tokens for the platforms you use. Any platform block you omit is simply unavailable for that account. A minimal Google-only account:

{
  "id": "my-account",
  "name": "My Account",
  "google_ads": {
    "customer_id": "1234567890",
    "refresh_token": "1//0e...",
    "currency": "EUR"
  }
}

Add as many clients/*.json files as you have accounts. They are git-ignored (only _example.json is tracked). The id field is the client_id you pass to every tool.

Getting tokens

# Google Ads OAuth refresh token (uses GOOGLE_ADS_CLIENT_ID/SECRET from .env)
npm run auth:google

# TikTok access token (uses TIKTOK_APP_ID/SECRET from .env)
npm run auth:tiktok

For Meta, generate a long-lived System User token in Business Settings and paste it into your account file's meta_ads.access_token.

Connecting to an MCP client

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ads-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/ads-analytics-mcp/dist/index.js"]
    }
  }
}

Claude Code

claude mcp add ads-analytics -- node /absolute/path/to/ads-analytics-mcp/dist/index.js

Then ask things like "List my accounts" or "Show last 30 days Google Ads campaign performance for my-account." When more than one account is configured, pass client_id (the account's id).

The Claude intelligence layer

Everything under .claude/ is an opinionated layer that sits on top of the raw tools. It is what turns "here are the numbers" into "here is what's wrong and what to do about it," tuned for Spanish (EU) advertisers. If you use a non-Claude MCP client, you can ignore this section. The tools work without it.

It has three parts: skills (entry points), subagents (deep workers), and references (the shared knowledge base they both cite).

Skills

Skills live in .claude/skills/<name>/SKILL.md. Each one activates on natural-language triggers, resolves inputs (client_id, date range), pulls data with the MCP tools, and either answers inline or hands off to a subagent for a full scored audit.

Per-platform skills (one entry point per channel):

Cross-platform skills (work across all three channels at once):

Subagents

Subagents live in .claude/agents/<name>.md. They are the deep workers a skill hands off to. Each runs a self-contained, scored audit and writes a Markdown report to ./reports/<client_id>/<date>-<platform>-audit/. The first line of every report is a machine-readable score line:

SCORE: <0-100>/100 GRADE: <A|B|C|D|F> CLIENT: <client_id> PLATFORM: <platform> PERIOD: <start>..<end>

business-analyst is the capstone: it does not call the platform tools itself. It consumes the reports written by the four audit agents and produces a unified cross-channel executive narrative with budget-reallocation recommendations.

Reference knowledge base

Both skills and agents are forbidden from inventing thresholds. They must cite these shared files in .claude/references/:

This is why the audits are tuned for Spain: a campaign sitting below an average but with healthy ROAS is scored WARN, not FAIL, and US-specific rules (CCPA, ECPC-only logic, Offline Conversions API) are flagged as out-of-date or out-of-scope.

How skills, agents, and tools play together

A typical full request flows top-to-bottom through all three layers:

User: "Audit my TikTok account for client maganda, last 14 days"
   │
   ▼
Skill  tiktok-ads        ── resolves client_id via list_clients
   │                        reads benchmarks-spain + compliance + platform-specs
   │                        decides: full audit → hand off
   ▼
Agent  audit-tiktok      ── parallel MCP calls:
   │                        get_tiktok_campaign_performance
   │                        get_tiktok_ad_performance      (2s/6s hold)
   │                        get_tiktok_hourly_performance
   │                        get_tiktok_auction_rankings
   │                        get_tiktok_anomaly_signal
   │                     ── scores each check vs benchmarks-spain.md
   ▼
Tools  get_tiktok_*      ── services/ normalize → adapters/ → TikTok Marketing API
   │
   ▼
Report ./reports/maganda/2026-06-28-tiktok-audit/TIKTOK-ADS-REPORT.md
        SCORE: 72/100 GRADE: C CLIENT: maganda PLATFORM: tiktok_ads PERIOD: ...

Run all three platform audits plus the budget review, then ask business-analyst to synthesize. It reads those four reports and produces the blended cross-channel view. A quick question ("what's my Meta CPA this week?") never leaves the skill: it pulls one tool and answers inline, no report written.

The contract between layers is deliberately thin: skills and agents only ever touch the platform through the 16 documented tool names. Add a new tool in src/tools/, rebuild, and reference it by name in a skill or agent. No other wiring required.

Development

npm run dev        # tsx watch, hot-reloads src/ on save
npm run typecheck  # tsc --noEmit, type-check without emitting
npm run build      # compile to dist/
npm start          # run the compiled server (node dist/index.js)

Architecture

src/
  index.ts         entry point (stdio transport)
  server.ts        MCP server wiring (ListTools / CallTool)
  config/          app-level config (env) + account registry (clients/*.json)
  schemas/         zod schemas for inputs, normalized output, account config
  tools/           MCP tool definitions + handlers (one file per platform area)
  services/        per-platform orchestration + normalization
  adapters/        the only layer that knows each platform's API shapes
  utils/           dates, logging, metric math

.claude/
  skills/          natural-language entry points (per-platform + cross-platform)
  agents/          deep audit subagents + the cross-channel business-analyst
  references/      Spain benchmarks, EU compliance, creative specs

Data flows tools → services → adapters → platform API on the way out, and the reverse, normalized, on the way back. adapters/ is the only layer that knows a platform's raw API shape; everything above it speaks the normalized vocabulary.

Security

• Never commit .env or real clients/*.json files, both are git-ignored.

• The repository ships only *.example placeholders.

• Tokens are read at runtime and used solely to call the official platform APIs.

• All 16 tools are read-only. The server has no write path to any ad account.

License

MIT