MCP Ads

Open-source (MIT) MCP server for Google Ads, Meta Ads (Facebook & Instagram),
GA4, Search Console, Tag Manager, TikTok, LinkedIn, Microsoft Ads and more.
Works with Claude, Claude Code, ChatGPT, Cursor, Codex, Gemini CLI, or any MCP
client. Read performance, audit wasted spend, build reports, and create or
change campaigns. Everything it creates starts paused until you say otherwise.

How it compares with the platforms' own servers (September 2026):

| | Google's Google Ads MCP | Meta's Ads MCP | MCP Ads |
|---|---|---|---|
| Google Ads | Reporting and diagnostics (read-only) | — | ~755 actions, read and write |
| Meta Ads | — | Reporting and campaign management | 234 actions, read and write |
| GA4, Search Console, GTM, TikTok, LinkedIn, Microsoft, Snapchat | — | — | Yes, in the same server |
| Hosting | Self-host | Hosted by Meta | Self-host (this repo) or hosted |

Use Google's or Meta's server if you only need one platform and want the vendor's
own code. Use this one if you want one server across platforms, or write access
to Google Ads.

~3,100 registered actions across 12+ platforms, exposed through 17 category
dispatchers so your agent loads ~20 tool definitions instead of thousands.

---

Choose your path

☁️ Cloud — connected in 2 minutes, free tier

Go to mcp-ads.com, sign in, OAuth your ad accounts
in the browser, and paste one URL into Claude. Done.

- No API applications, no developer tokens, no app reviews — the platform
approvals (Google Ads developer token, Meta App Review, and the rest) are
already in place
- Free tier: 30 tool calls/month, every platform. Paid plans for unlimited use
- Your credentials stored encrypted; revoke any time from the dashboard

This is the right choice for almost everyone who wants to use the tools
rather than host them.

🔧 Self-hosted — free forever, your keys, your machine

Clone this repo and run it with your own platform credentials. MIT licensed,
no strings, no phone-home. Your tokens never leave your machine.

The honest cost: several of the ad platforms make you apply for API access
(see the table below). If you already have those credentials — you're an
agency with a Google Ads developer token, a developer with a reviewed Meta
app — self-hosting takes minutes. If you don't, budget days to weeks for the
platforms' own approval queues, or just use the cloud.

Same code, same actions, either way. The hosted product is this exact
server plus multi-user auth and the approvals already done.

---

Self-hosted quick start

git clone https://github.com/RoyAzran/mcp-ads.git
cd mcp-ads
pip install -r requirements.txt
cp .env.example .env      # fill in the platforms you use
python server.py doctor   # shows what's connected

Then add it to Claude Desktop (claude_desktop_config.json) or
Claude Code (.mcp.json):

{
  "mcpServers": {
    "mcp-ads": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-ads/server.py"]
    }
  }
}

That's the whole install. Ask your agent "audit my Google Ads wasted spend"
and watch it go.

Docker instead:

cp .env.example .env
docker compose up -d      # HTTP server on 127.0.0.1:8000, MCP endpoint at /mcp

HTTP mode without Docker: python server.py serve --transport http

OAuth helper for the bearer-token platforms (opens a browser, stores and
auto-refreshes the token):

python server.py auth snapchat_ads

What works out of the box, honestly

Self-hosting means holding your own keys to each platform. Some hand them
over in minutes; some make you apply. This is the real picture:

| Platform | Actions | What you need | Realistic effort |
|---|---|---|---|
| GA4 | 95 | Google OAuth client + refresh token | Minutes–hours |
| Search Console | 23 | Same Google token | Minutes |
| Tag Manager | 64 | Same Google token | Minutes |
| Google Sheets | 69 | Same Google token | Minutes |
| WordPress | ~1,800 | Site URL + Application Password | Minutes |
| Google Ads | ~755 | Above plus a developer token (Google reviews the application) | 1–3 weeks |
| Meta Ads | 234 | A Meta app; ads_management/ads_read need App Review (works for the app's own admins/testers before approval) | Days for yourself, weeks for App Review |
| Snapchat Ads | 12 | Self-serve OAuth app in Business Manager | Hours |
| Microsoft Ads | 11 | Entra OAuth app + developer token (sandbox instant, production reviewed) | Hours–days |
| TikTok Ads | 35 | Business API app review | Weeks |
| LinkedIn Ads | 26 | Marketing Developer Platform approval — routinely refused to individuals | Often unobtainable |
| Meta Ad Library | 7 | Token from a Meta-ID-verified identity | Days |
| Ads Transparency | 7 | Nothing — but read the note below | Off by default |
| Creative generation | 7 | Your OpenAI API key | Minutes |

If that table makes you tired, that's exactly what
the cloud version is for — the approvals are done,
you just connect your accounts.

How the tool surface works

Your agent sees one dispatcher per platform plus list_actions:

1. list_actions(category="meta_ads_action", search="budget")
2. meta_ads_action(action="<name from step 1>", params={...})

- Write actions create everything paused unless explicitly told to launch
- Role gating (permissions.py) separates read from write tools by name
- --surface full registers every action as its own MCP tool instead —
useful for programmatic clients, far too many tools for a chat client

The NPX CLI

No Python on the client machine? The CLI is a ~300-line stdio proxy
(cli/) that forwards to any MCP Ads server:

```bash