io.github.AleemHaider/google-ads-manager-mcp

Google Ads Manager MCP

Unofficial, community-maintained project. Not affiliated with, endorsed by, or sponsored by Google. "Google Ads" is a trademark of Google LLC.

A local MCP (Model Context Protocol) server that lets an AI assistant read and manage a Google Ads account: run GAQL reports, create campaigns, pause/enable campaigns, and add keywords.

Google also publishes an official Google Ads MCP server, which is read-only (reporting/diagnostics only). This project covers the same reporting ground and adds write support — creating and editing campaigns, budgets, ad groups, keywords, and ads — gated behind a draft/confirm safety layer so nothing changes in your account by accident.

Every write goes through a draft → confirm safety flow: the tool that "creates" or "updates" something only validates the change against Google's API (validate_only) and hands back a draftId with a preview. Nothing changes in your Ads account until you call confirm_write with that draftId. Drafts expire after 10 minutes.

Tools

Read-only:

• list_accessible_customers — which accounts this refresh token can reach
• search_gaql — run any raw GAQL SELECT query
• get_campaigns — campaigns with status, budget, and core metrics
• get_ad_groups — ad groups (optionally filtered to a campaign) with metrics
• get_keywords — keyword criteria with match type, status, and metrics
• get_search_terms — actual search terms that triggered your ads, for finding negative keyword candidates

Write (draft → confirm):

• create_campaign — new campaign + budget, created PAUSED unless you say otherwise
• update_campaign_status — enable / pause / remove a campaign
• update_campaign_budget — change an existing campaign's daily budget
• add_keywords — add keyword criteria to an ad group
• create_ad_group — new ad group inside an existing campaign
• update_ad_group_status — enable / pause / remove an ad group
• update_keyword_status — enable / pause / remove a keyword criterion
• add_negative_keywords — add negative keyword criteria to an ad group
• create_responsive_search_ad — new responsive search ad, created PAUSED unless you say otherwise
• confirm_write — execute a previously returned draftId for real

Setup

1. Google Ads developer token

Google Ads → Tools & Settings → API Center. Test-account tokens are issued instantly; a production-level token requires Google's manual review (roughly 1-2 weeks), so apply for that early if you'll use this beyond a test account.

2. OAuth client

Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID. Choose application type Desktop app. Copy the client ID and client secret.

3. Configure environment

cp .env.example .env

Fill in GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_DEVELOPER_TOKEN, and GOOGLE_ADS_CUSTOMER_ID (the account this server should manage — 10 digits, dashes optional). If that account is a client under a manager (MCC) account, also set GOOGLE_ADS_LOGIN_CUSTOMER_ID to the manager account's ID.

4. Get a refresh token

npm install
npm run auth

This opens an authorization URL — open it, sign in with the Google account that has access to your Ads account, approve the adwords scope. The script prints a GOOGLE_ADS_REFRESH_TOKEN; add it to .env.

5. Build

npm run build

6. Point your MCP client at it

For Claude Desktop / Claude Code, add to your MCP config:

{
  "mcpServers": {
    "google-ads-manager": {
      "command": "node",
      "args": ["/absolute/path/to/google ads manger mcp/build/index.js"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "..."
      }
    }
  }
}

(Or skip the env block and just make sure .env is populated — the server loads it via dotenv when run directly, e.g. npm run dev during local iteration.)

Notes

• This is scoped to a single Google Ads account (GOOGLE_ADS_CUSTOMER_ID). To manage several client accounts under one manager account, either run one instance per customer ID, or extend googleAdsClient.ts to accept a customerId argument per tool call.
• New campaigns default to PAUSED (startEnabled: false) so nothing spends until you explicitly enable it.

Contributing

Issues and PRs welcome — new report types, negative-keyword-at-campaign-level support, and multi-account (MCC) handling are the most useful next additions.

License

MIT