Ads MCP server

ads-mcp

An MCP server wrapping the Google Ads API and Meta Marketing API directly, with no third-party quota or middleman. Point an MCP-compatible client at it and manage Search campaigns, keywords, ads and Meta ad review status straight against Google's and Meta's own APIs.

Every write tool that could spend money is safe by default: googleadscreatesearchcampaign always creates campaigns PAUSED, and the only tools that can turn spend on are googleadssetcampaignstatus / metaadssetcampaignstatus, called explicitly.

Setup

Credentials require logins and business identity only you have; nothing here can be automated.

Google Ads

1. Google Cloud project + OAuth client: console.cloud.google.com, new (or existing) project, APIs & Services, Credentials, Create OAuth client ID (type: Desktop app). Copy the Client ID/Secret into .env.
2. Under that OAuth client, add http://localhost:8787/oauth2callback as an authorized redirect URI.
3. Developer token: ads.google.com/aw/apicenter, apply for a token. Basic access is free and usually approved within a few days; it allows ~15,000 operations/day. Put it in .env as GOOGLEADSDEVELOPER_TOKEN.
4. Run pnpm install then pnpm google:auth, this opens a browser, you sign in and consent, and it prints a refresh token to paste into .env as GOOGLEADSREFRESH_TOKEN.
5. Set GOOGLEADSCUSTOMERID to the 10-digit account ID (no dashes) these tools should operate on by default. If that account is managed under an MCC account, also set GOOGLEADSLOGINCUSTOMER_ID to the MCC's ID.

Meta Ads

1. Meta App: developers.facebook.com, My Apps, Create App (type: Business). Copy the App ID/Secret from Settings, Basic into .env.
2. Request the adsmanagement permission under App Review. This needs Business Verification** (documents proving the business is real) and usually a short screen-recording demo of the exact use case. This step is slow, budget for weeks, not days.
3. Once approved, generate a long-lived System User access token (Business Settings, System Users) with adsmanagement scope on the ad account, and put it in .env as METAACCESS_TOKEN.
4. Set METAADACCOUNTID to the numeric account ID (no act prefix needed, the client adds it).

Running

pnpm install
pnpm dev        # runs the MCP server over stdio via tsx, for local testing
pnpm build && pnpm start   # compiled version

Once published to npm, it also runs via npx @gudlab/ads-mcp, no local clone needed. Point an MCP-compatible client at it, e.g. in Claude Code's .mcp.json:

{
  "mcpServers": {
    "ads-mcp": {
      "command": "npx",
      "args": ["-y", "@gudlab/ads-mcp"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "...",
        "META_APP_ID": "...",
        "META_APP_SECRET": "...",
        "META_ACCESS_TOKEN": "...",
        "META_AD_ACCOUNT_ID": "..."
      }
    }
  }
}

Before that's published, point it at the local build instead: command: "node", args: ["/path/to/ads-mcp/dist/index.js"], or command: "pnpm", args: ["dev"] with cwd set to this directory for local iteration.

First real run: verify before trusting it

The Google Ads and Meta Marketing APIs both shift field/enum names across versions, so before relying on any tool here for real campaign work:

1. Run googleadslistcampaigns / metaadslistcampaigns first, read-only, the cheapest way to confirm auth and the client libraries are wired correctly.
2. Test googleadscreatesearchcampaign on a throwaway campaign name, then check it directly in the Google Ads UI rather than trusting the tool's own response as proof of correctness.
3. Only after that, use it for real campaign work.

Tool reference

Shortened. The full README is on GitHub.