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 the full Meta campaign lifecycle (create, publish, monitor, report) against Google's and Meta's own APIs.

Every write tool that could spend money is safe by default: google_ads_create_search_campaign and every Meta create/copy tool always create objects PAUSED. The only tools that can turn spend on are google_ads_set_campaign_status and meta_ads_set_campaign_status / meta_ads_set_ad_set_status / meta_ads_set_ad_status, called explicitly.

Setup

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

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 (System User token)

A personal user token dies when Facebook shows a login checkpoint (Graph error 190 / subcode 459). A Business Manager System User token is the supported way to keep Marketing API access independent of a person's browser session.

1. Meta App: developers.facebook.com, My Apps, Create App (type: Business). Copy the App ID and App Secret from Settings > Basic into .env as META_APP_ID / META_APP_SECRET.
2. Business Manager: open business.facebook.com > Business Settings.
3. Create a System User: Users > System Users > Add. Admin is simplest for ad account + Page + pixel assignment. Name it something like ads-mcp.
4. Assign assets to that System User (Add Assets):
   • Ad account: allow manage campaigns (or full control).
   • Facebook Page used in creatives: allow create content / manage ads (or full control).
   • Pixel used for optimization: allow advertise.
5. Generate a token: on the System User, Generate New Token. Select the app from step 1. Request at least:
   • ads_management
   • ads_read
   • business_management
   • pages_show_list
   • pages_read_engagement
   • pages_manage_ads (needed to create unpublished Page posts / link creatives) Choose a never-expiring token if the UI offers it.
6. Put the token in .env as META_ACCESS_TOKEN. Never commit it.
7. Set META_AD_ACCOUNT_ID to the numeric account ID (act_ prefix optional). Optionally set META_PAGE_ID and META_PIXEL_ID so create tools do not need them on every call.
8. Optional: META_GRAPH_API_VERSION pins the Graph version. Default is v26.0.

App Review / Development mode. If the app, ad account, Page and pixel all belong to the same Business, a System User token usually works while the app is in Development mode (Standard Access) without App Review. Advanced Access and App Review are required to manage other businesses' ad accounts, or when the app is Live and those permissions are restricted. ads_management and the pages_* permissions are the ones Meta most often holds behind review.

Housing, employment, credit, and (in some regions) financial products and services ads must set special_ad_categories accordingly (HOUSING, EMPLOYMENT, CREDIT, FINANCIAL_PRODUCTS_SERVICES). Those campaigns have extra targeting limits; Advantage+ may be required or forbidden depending on the category.

Call meta_ads_get_account first. If META_APP_ID and META_APP_SECRET are set, the response includes token debug (scopes, expiry).

Graph errors this server rewrites

Running

pnpm install
pnpm test
pnpm dev        # MCP server over stdio via tsx
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": "...",
        "META_PAGE_ID": "...",
        "META_PIXEL_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_get_account / 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 or meta_ads_create_campaign on a throwaway name, then check it in the ads UI rather than trusting the tool's own response as proof of correctness.
3. Only after that, use *_set_*_status with ACTIVE on a real campaign.

End-to-end Meta example (always paused until the last step)

Budgets are in the ad account currency (e.g. 20 means 20 GBP, sent to Graph as 2000 minor units).

1. meta_ads_get_account
     Confirm the token is valid and the account currency / timezone.

2. meta_ads_search_targeting
     { "q": "online shopping", "type": "interest" }
     Copy an interest id from the results. Some detailed interests have been retired by Meta; try a broader query or type=behavior if this is empty.

3. meta_ads_estimate_audience
     { "targeting": { "countries": ["GB"], "age_min": 25, "age_max": 54, "interests": [{ "id": "6003139266461" }] },
       "optimization_goal": "OFFSITE_CONVERSIONS" }

4. meta_ads_create_campaign
     { "name": "UK leads - paused",
       "objective": "OUTCOME_LEADS",
       "special_ad_categories": [] }
     Returns campaign_id. Status is PAUSED.

5. meta_ads_create_ad_set
     { "campaign_id": "<campaign_id>",
       "name": "GB 25-54 shopping",
       "daily_budget": 15,
       "optimization_goal": "OFFSITE_CONVERSIONS",
       "billing_event": "IMPRESSIONS",
       "custom_event_type": "COMPLETE_REGISTRATION",
       "advantage_audience": false,
       "targeting": {
         "countries": ["GB"],
         "age_min": 25,
         "age_max": 54,
         "interests": [{ "id": "6003139266461", "name": "Online shopping" }]
       } }
     Advantage+ audience is off (`targeting_automation.advantage_audience = 0`). Status is PAUSED.

6. meta_ads_upload_image
     { "url": "https://example.com/ads/hero.jpg" }
     or { "path": "/absolute/path/hero.jpg" }
     Returns hash.

7. meta_ads_create_ad_creative
     { "name": "Homepage v1",
       "link": "https://example.com/?utm_source=meta",
       "message": "Open an account from your banking app.",
       "headline": "Pay from your bank",
       "description": "No card needed.",
       "image_hash": "<hash>",
       "cta_type": "LEARN_MORE",
       "url_tags": "utm_source=meta&utm_medium=paid&utm_campaign=uk_leads" }

8. meta_ads_create_ad
     { "name": "Ad 1", "ad_set_id": "<ad_set_id>", "creative_id": "<creative_id>" }
     Status is PAUSED. Still no spend.

9. Activate spend, in this order (or campaign last):
     meta_ads_set_ad_status          { "ad_id": "<ad_id>", "status": "ACTIVE" }
     meta_ads_set_ad_set_status      { "ad_set_id": "<ad_set_id>", "status": "ACTIVE" }
     meta_ads_set_campaign_status    { "campaign_id": "<campaign_id>", "status": "ACTIVE" }

10. meta_ads_get_ad_status
      Review / rejection lives in ad_review_feedback and issues_info.

11. meta_ads_get_insights
      { "level": "campaign", "object_id": "<campaign_id>", "date_preset": "last_7d" }
      Optional: "breakdowns": ["age", "gender", "placement", "day"]
      or "since": "2026-10-01", "until": "2026-10-07"

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), all names prefixed meta_ads_:

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.