io.github.gudlab/ads-mcp

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: google_ads_create_search_campaign always creates campaigns PAUSED, and the only tools that can turn spend on are google_ads_set_campaign_status / meta_ads_set_campaign_status, 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 GOOGLE_ADS_DEVELOPER_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 GOOGLE_ADS_REFRESH_TOKEN.
5. Set GOOGLE_ADS_CUSTOMER_ID 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 GOOGLE_ADS_LOGIN_CUSTOMER_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 ads_management 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 ads_management scope on the ad account, and put it in .env as META_ACCESS_TOKEN.
4. Set META_AD_ACCOUNT_ID 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 google_ads_list_campaigns / meta_ads_list_campaigns first, read-only, the cheapest way to confirm auth and the client libraries are wired correctly.
2. Test google_ads_create_search_campaign 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

Google Ads (src/google-ads/tools.ts): list_campaigns, get_campaign_structure, create_search_campaign (always PAUSED), add_keywords, set_keyword_status (pause/enable, reversible), remove_keywords (permanent, requires confirm_delete: true), update_bid_strategy, add_negative_keywords, set_campaign_status (the only enable/spend switch).

Meta Ads (src/meta-ads/tools.ts): list_campaigns, get_ad_status (pulls ad_review_feedback/issues_info, the actual rejection reason for a disapproved ad), list_ads_by_status (e.g. pull every DISAPPROVED ad in one call), set_campaign_status (the only enable/spend switch).

Privacy and data handling

All credentials stay in your own .env (never committed, see .gitignore) or your MCP client's own env config, and are used only to call Google's and Meta's APIs directly from your machine. This server sends nothing to any third party: no telemetry, no analytics, no relay service. Every request goes straight from your process to googleads.googleapis.com or graph.facebook.com, using your own developer token and access token.

License

MIT, see LICENSE.