google-ads-mcp

Run your Google Ads account from Claude, Codex, or any AI assistant, in plain English.

Ask for a report, launch a campaign, tune bids and budgets, manage keywords, or build Performance Max assets, all by chatting. It's an MCP server, so it plugs into any AI harness that speaks MCP: Claude Code, Claude Desktop, OpenAI Codex, Cursor, LibreChat, and others.

The important part: reads are free and can never spend, and every write previews first. The assistant shows you the exact values and asks you to type yes or ok in chat; only then does it apply with confirmed:true and user_confirmation. New campaigns start paused. You get an AI copilot for Google Ads without pretending the model is a free pass on your budget.

Money and residual risk: once something is enabled or a budget goes up, Google can spend real money. Previews and yes/ok are guardrails, not a bank lock, MCP cannot force a human click, and a sloppy model could invent approval. Read the preview. If you would not hit Apply in the Google Ads UI, do not type yes here. See Money and safety and SECURITY.md.

You:  How did my campaigns do last month?
AI:   (pulls a report: clicks, cost, conversions, ROAS by campaign)

You:  Create a paused search campaign "Summer Sale" with a $20/day budget.
AI:   (shows a preview of exactly what it will create)
      Type yes or ok to create it, or anything else to cancel.
You:  yes
AI:   Created "Summer Sale" (PAUSED). It won't serve until you enable it.

Contents

• Quick start
• What it can do
• What this is not
• Money and safety
• Add it to your AI harness
• Credentials (and Getting a refresh token)
• Configuration (and all environment variables)
• Hosted, multi-user (and LibreChat on the same host)
• Tools
• Coverage
• Big reports and pagination
• Scheduled and unattended use
• Troubleshooting
• Notes
• Acknowledgments
• Disclaimer
• License
• Contributing

Quick start

# 1) Credentials: developer token + OAuth client + refresh token + customer id
#    (see Credentials below). Put them in your shell or MCP client env.

# 2) Run via npx (no install), stdio is the default
npx -y @aligulzar729/google-ads-mcp --help

# 3) Or clone and develop
git clone https://github.com/aligulzar729/google-ads-mcp.git
cd google-ads-mcp
npm ci
cp .env.example .env   # fill in values
npm run dev:stdio      # or: npm run dev:http

Node 22.5+ is required. There is no native build step and no database to run: HTTP mode uses Node's built-in SQLite, so npx just works.

What it can do

• Reporting: campaign performance, Search impression share, Performance Max asset groups, and raw GAQL for anything else. It looks up real field names first, so queries don't fail on guessed fields.
• Campaigns: create Search, Display, Demand Gen, App, Shopping, and Performance Max campaigns (use Demand Gen for YouTube; Google no longer lets the API create Video campaigns); rename, set dates and networks, pause and resume, set budgets and bidding strategies, and target by location, language, and schedule.
• Ad groups and ads: manage ad groups and build ads per channel (responsive search, responsive display, HTML5, Demand Gen, video, app, shopping).
• Keywords: list with quality score, add positive or negative keywords, change bids and status.
• Performance Max: create asset groups from text and images, update or delete them, add more images, list and remove assets.
• Accounts: check the connection and list the accounts you can reach; on the hosted (HTTP) server, also switch the active account and read an audit trail of every change.

What it can't do

• Conversion tracking. Creating or editing conversion actions and importing offline conversions (it reads conversion metrics, but doesn't set them up).
• Audiences and bid adjustments. Remarketing or customer-match lists, audience targeting, and device, demographic, or audience bid modifiers. Targeting here is location, language, and ad schedule only.
• Search ad assets / extensions. Sitelinks, callouts, structured snippets, call, price, and promotion assets (Performance Max text and image assets are supported).
• Account structure and budgets. Creating customer accounts, managing an MCC hierarchy, or setting up billing and account-level budget orders.
• Experiments, drafts, and recommendations. A/B experiments, campaign drafts, and applying Google's optimization-score recommendations.
• Shared library and labels. Shared budgets, negative-keyword and placement-exclusion sets, and labels.
• Keyword Planner. Keyword ideas and traffic forecasts.
• External links. Merchant Center, Analytics, and YouTube account links (Shopping and Performance Max assume these already exist).

What this is not

• Not the Google Ads UI. There is no full visual editor, no Auction Insights dashboard, no Billing center. For some jobs you still open ads.google.com.
• Not an autopilot. It does not decide strategy for you, watch ROAS overnight, or "just run ads." You (or a human who knows the account) still choose what to build and what to enable.
• Not a guarantee of perfect model behavior. Tool text tells the assistant to preview and wait for your yes/ok. Most models will. Some will not. Stay in the loop on anything that spends or deletes.
• Not a substitute for access control. Whoever can talk to this server with your credentials can attempt the same changes you can. Use least-privilege Google users, and do not point a public bot at a high-spend account for fun.
• Not offline magic. It talks to the real Google Ads API. Bad GAQL, wrong customer id, or a Testing-mode OAuth app will fail the same way they would in any other client.

If you want a report in chat, a careful campaign draft, or help wiring keywords and P-Max assets with a human still holding the wheel, you are in the right place. If you want unsupervised budget AI, you are not.

Money and safety

Reads never cost anything. Writes can, and every write previews first: the model shows the exact values and asks you to type yes or ok; apply then requires confirmed:true and user_confirmation "yes" or "ok" (REQUIRE_USER_CONFIRMATION, default on).

| Action | Money impact | |--------|----------------| | Reports, lookups, list ads, connection status | None. Free. | | Create campaign / P-Max asset group | Paused by default, no serving, no spend until something is enabled. | | Raise daily budget, change bids, enable a campaign or ad group | Can spend as soon as Google serves. | | Pause or remove | Stops or deletes serving; removes are permanent for that entity. |

More guardrails: new campaigns and P-Max asset groups start paused; deletes show a clear warning first (also gated by REQUIRE_USER_CONFIRMATION); every applied change lands in a durable audit log; and HTTP mode rate-limits OAuth and /mcp per client IP (process-local, put a reverse proxy in front for multi-replica).

Habits that save pain:

• Start on a test or low-budget account while you learn the tools.
• Treat yes like approving a wire: skim the preview numbers (budget, bid, status) before you type it.
• Prefer PAUSED creates, then enable only what you meant to turn on.
• Shared budgets are shared: changing one campaign's budget can hit every campaign on that budget (the tools warn when they can).

REQUIRE_USER_CONFIRMATION=false disables the chat yes/ok so one-shot confirmed:true works, for trusted headless automation only. On a live account with real spend, leave it on.

You are responsible for the Google Ads account and any charges from it. This is MIT software that talks to Google's API; it does not pay your media bill and does not absorb mistakes.

Add it to your AI harness

For a single account on your own machine, most people use the stdio mode below. For a shared, multi-user deployment where each person signs in with their own Google account, see Hosted, multi-user.

Add it from the CLI (put the server name right after add, then the env vars):

claude mcp add google-ads \
  --env GOOGLE_ADS_DEVELOPER_TOKEN=... \
  --env GOOGLE_OAUTH_CLIENT_ID=... \
  --env GOOGLE_OAUTH_CLIENT_SECRET=... \
  --env GOOGLE_ADS_REFRESH_TOKEN=... \
  --env GOOGLE_ADS_CUSTOMER_ID=... \
  -- npx -y @aligulzar729/google-ads-mcp

Or add it to .mcp.json (shared with a project) or ~/.claude.json (just you):

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@aligulzar729/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_OAUTH_CLIENT_ID": "...",
        "GOOGLE_OAUTH_CLIENT_SECRET": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "..."
      }
    }
  }
}

Edit the config file (Settings, then Developer, then Edit Config), or open it directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@aligulzar729/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_OAUTH_CLIENT_ID": "...",
        "GOOGLE_OAUTH_CLIENT_SECRET": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "..."
      }
    }
  }
}

Restart Claude Desktop after editing.

Add it from the CLI:

codex mcp add google-ads -- npx -y @aligulzar729/google-ads-mcp

Or edit ~/.codex/config.toml directly. The table name must be mcp_servers with an underscore:

[mcp_servers.google-ads]
command = "npx"
args = ["-y", "@aligulzar729/google-ads-mcp"]
env = { GOOGLE_ADS_DEVELOPER_TOKEN = "...", GOOGLE_OAUTH_CLIENT_ID = "...", GOOGLE_OAUTH_CLIENT_SECRET = "...", GOOGLE_ADS_REFRESH_TOKEN = "...", GOOGLE_ADS_CUSTOMER_ID = "..." }

LibreChat connects over HTTP and lets each user sign in with their own Google account, so you run the server yourself (see Hosted, multi-user) and point LibreChat at it:

mcpServers:
  GoogleAds:
    type: streamable-http
    url: "https://your-subdomain.example.com/mcp"
    startup: false
    requiresOAuth: true

Two settings matter:

• requiresOAuth: true declares this a per-user OAuth server. Without it, LibreChat tries to auto-detect OAuth by opening an unauthenticated connection to list tools, which always fails on an auth-walled server and fills your logs with OAuth not supported in unauthenticated discovery and repeated Reinspection failed ... timeout. The flag skips that probe and shows the sign-in prompt directly.
• startup: false connects on first use, not at boot, since there is no user to authorize at startup.

Also add the host to mcpSettings.allowedDomains in librechat.yaml. Users then click Connect in chat and approve at Google. Nothing to paste. To run LibreChat and this server on one machine with no public URL, see LibreChat on the same host.

Add an MCP server entry (Cursor: Settings → MCP; VS Code Copilot: MCP config) equivalent to:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@aligulzar729/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_OAUTH_CLIENT_ID": "...",
        "GOOGLE_OAUTH_CLIENT_SECRET": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "..."
      }
    }
  }
}

Exact JSON key names vary slightly by client (mcpServers vs servers); keep command / args / env the same.

Single user, over stdio: run npx -y @aligulzar729/google-ads-mcp with the five GOOGLE_ADS_* / GOOGLE_OAUTH_* env vars set, using whatever command / args / env shape your client expects.

Multi-user, over HTTP: run it in --http mode behind HTTPS and point your client at https://<host>/mcp. Any client that supports streamable-http with OAuth (dynamic client registration plus PKCE) can connect. See Hosted, multi-user.

Credentials

Three values are always required, because they identify the app (not the user):

• GOOGLE_ADS_DEVELOPER_TOKEN: from your Google Ads manager account, under API Center. Apply for Standard Access before you run production volume.
• GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET: an OAuth client from a Google Cloud project that has the Google Ads API enabled.

For local (stdio) use, add one account's own credentials:

• GOOGLE_ADS_REFRESH_TOKEN: a refresh token for a Google account with access to the ads account. See Getting a refresh token below.
• GOOGLE_ADS_CUSTOMER_ID: the account you act on, 10 digits with no dashes. Its campaigns and reports are what you read and change.
• GOOGLE_ADS_LOGIN_CUSTOMER_ID: optional. The manager (MCC) account you reach that account through, if any.

These two trip everyone up, so plainly: CUSTOMER_ID is which account to act on, LOGIN_CUSTOMER_ID is which manager to go through to reach it. A manager (MCC) account holds no campaigns itself; it just grants access to the client accounts under it. So:

• Your Google user has direct access to the account (it shows as [client] in google_ads_account list): set CUSTOMER_ID to it and leave LOGIN_CUSTOMER_ID empty.
• You only reach the account through a manager: set CUSTOMER_ID to the client account and LOGIN_CUSTOMER_ID to that manager's id, never to the client id, and never to a manager that does not actually own the client (both cause PERMISSION_DENIED).

Keep the OAuth app in the In Production publishing status. In Testing, refresh tokens expire after 7 days.

For hosted (http) use you don't set a refresh token at all. Users authorize themselves in the browser and the server stores each token encrypted. See below.

Getting a refresh token (OAuth Playground)

For stdio mode you supply one account's refresh token. Two settings are what everyone gets wrong, so both steps below are required:

1. Add the Playground redirect to your OAuth client. In Google Cloud Console, open your OAuth client (the one whose id and secret you use) under APIs & Services, then Credentials. Under Authorized redirect URIs, add https://developers.google.com/oauthplayground and save. Miss this and the Playground fails with redirect_uri_mismatch.
2. Use your own client in the Playground. Open the OAuth 2.0 Playground, click the gear (top right), check Use your own OAuth credentials, and paste the same client id and secret. Miss this and the token is minted for Google's demo client, which later fails with unauthorized_client.
3. Authorize the Ads scope. In the left panel under "Input your own scopes", enter https://www.googleapis.com/auth/adwords, click Authorize APIs, and sign in with the Google account that can reach the ads account.
4. Exchange for the token. Click Exchange authorization code for tokens and copy the refresh_token into GOOGLE_ADS_REFRESH_TOKEN.

A token works only when both are true: it was minted by your client (step 2) and your client permits the Playground redirect (step 1). The Playground redirect is only needed for minting, so you can remove it from the client afterward; it is separate from the PUBLIC_BASE_URL/auth/callback redirect that http mode registers.

Configuration

Everything is set through environment variables. Every setting can also be passed as a command-line flag: the flag is the env var name, lowercased, with dashes for underscores. A bare --flag sets true, and --no-flag sets false. Flags are handy in a client's args or a launch command:

npx -y @aligulzar729/google-ads-mcp \
  --app-name="Acme Ads" \
  --log-level=debug \
  --no-require-user-confirmation      # trusted automation only

"args": ["-y", "@aligulzar729/google-ads-mcp", "--app-name=Acme Ads"]

Prefer env vars for secrets: flags can show up in the process list.

All environment variables

App identity, required in both modes. These identify the app, not the user.

| Env var | Flag | Description | |---------|------|-------------| | GOOGLE_ADS_DEVELOPER_TOKEN | --google-ads-developer-token | Google Ads API developer token, from your manager account API Center. | | GOOGLE_OAUTH_CLIENT_ID | --google-oauth-client-id | OAuth client id from a Google Cloud project with the Google Ads API enabled. | | GOOGLE_OAUTH_CLIENT_SECRET | --google-oauth-client-secret | OAuth client secret. |

Behavior, both modes.

| Env var | Flag | Default | Description | |---------|------|---------|-------------| | APP_NAME | --app-name | Google Ads MCP | Name shown on the OAuth consent and error pages. | | LOG_LEVEL | --log-level | info | debug, info, warn, or error. | | REQUIRE_USER_CONFIRMATION | --no-require-user-confirmation | on | Gates every write, including deletes. Turn off only for trusted headless automation. |

stdio mode, single user. One account's own credentials.

| Env var | Flag | Default | Description | |---------|------|---------|-------------| | GOOGLE_ADS_REFRESH_TOKEN | --google-ads-refresh-token | empty | Refresh token for a Google account with access to the ads account. See Getting a refresh token. | | GOOGLE_ADS_CUSTOMER_ID | --google-ads-customer-id | empty | The account to act on (10 digits, no dashes). | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | --google-ads-login-customer-id | empty | The manager (MCC) to reach it through; leave empty for direct access. See Credentials. |

http mode, hosted and multi-user. Per-user credentials come from each user's browser sign-in, so you do not set a refresh token here.

| Env var | Flag | Default | Description | |---------|------|---------|-------------| | PORT | --port | 3001 | Listen port. | | PUBLIC_BASE_URL | --public-base-url | required | Public base URL of this instance. Register PUBLIC_BASE_URL/auth/callback as a redirect URI on the Google OAuth client. | | TOKEN_ENC_KEY | --token-enc-key | required | 32-byte base64 key (openssl rand -base64 32) that encrypts stored refresh tokens. Keep it stable and secret. | | ALLOWED_REDIRECT_ORIGINS | --allowed-redirect-origins | required | Comma-separated allowlist of client origins allowed to complete the OAuth flow, for example https://chat.example.com. | | AUDIT_DB_PATH | --audit-db-path | ./data/audit.db | Where the audit log and encrypted authorizations live. Mount a volume so it survives restarts. |

Hosted, multi-user

In --http mode the server is its own OAuth 2.1 authorization server that proxies Google. Each user signs in once, and their Google refresh token is stored encrypted on the server and never handed back to the client. This is how you offer Google Ads to a whole team from a shared chat app like LibreChat.

Run it (behind HTTPS, on its own subdomain):

npx -y @aligulzar729/google-ads-mcp --http

Beyond the shared app credentials, this mode needs TOKEN_ENC_KEY, PUBLIC_BASE_URL, and ALLOWED_REDIRECT_ORIGINS, plus optional PORT and AUDIT_DB_PATH (see All environment variables). Two things worth calling out: register PUBLIC_BASE_URL/auth/callback as a redirect URI on your Google OAuth client, and ALLOWED_REDIRECT_ORIGINS is the allowlist that stops a phished authorize link from delivering a code to an attacker.

A Dockerfile and docker-compose.yml are included for a container deployment.

Docker Compose (HTTP)

cp .env.example .env
# set GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_OAUTH_*, TOKEN_ENC_KEY,
# PUBLIC_BASE_URL=https://ads.example.com, ALLOWED_REDIRECT_ORIGINS=https://chat.example.com

docker compose up -d --build
curl -sS http://127.0.0.1:3001/healthz

Point your reverse proxy (TLS) at 127.0.0.1:3001. The whole subdomain must reach this container: OAuth discovery, /authorize, /token, and /mcp all live on the same host (PUBLIC_BASE_URL). Back up the ads_data volume (audit log + encrypted authorizations).

LibreChat on the same host (no public URL)

To run LibreChat and this server on one machine over plain HTTP, with no public domain or TLS, run this server as a sidecar that shares the LibreChat api container's network namespace. That makes http://localhost:3001 the same address for both your browser and LibreChat's backend, and Google allows http://localhost as the one non-HTTPS OAuth redirect, so sign-in works without a certificate.

Add to LibreChat's docker-compose.override.yml:

services:
  api:
    ports:
      - "3001:3001"                 # expose the sidecar to your browser
  google-ads-mcp:
    image: node:24-bookworm-slim
    command: ["npx", "-y", "@aligulzar729/google-ads-mcp", "--http"]
    network_mode: "service:api"     # share the api netns: one localhost for browser and backend
    depends_on:
      - api
    environment:
      PORT: "3001"
      PUBLIC_BASE_URL: "http://localhost:3001"
      ALLOWED_REDIRECT_ORIGINS: "http://localhost:3080"   # your LibreChat origin
      GOOGLE_ADS_DEVELOPER_TOKEN: ${GOOGLE_ADS_DEVELOPER_TOKEN}
      GOOGLE_OAUTH_CLIENT_ID: ${GOOGLE_OAUTH_CLIENT_ID}
      GOOGLE_OAUTH_CLIENT_SECRET: ${GOOGLE_OAUTH_CLIENT_SECRET}
      TOKEN_ENC_KEY: ${TOKEN_ENC_KEY}
      AUDIT_DB_PATH: /app/data/audit.db
    volumes:
      - ads_data:/app/data
volumes:
  ads_data:

Then:

• Point the LibreChat entry at url: "http://localhost:3001/mcp" with requiresOAuth: true (see LibreChat above), and keep localhost in mcpSettings.allowedDomains.
• Register http://localhost:3001/auth/callback as a redirect URI on the Google OAuth client.
• Sign in from Chrome or Firefox: the consent cookie is Secure, and those treat localhost as a secure context. Safari may refuse it.
• The sidecar shares the api container's network, so recreate both together after changes: docker compose up -d --force-recreate api google-ads-mcp.

Publish the OAuth app to In Production so per-user tokens do not expire after 7 days.

Tools

Seven tools, each takes an action:

| Tool | Actions | What it covers | |------|---------|----------------| | google_ads_account | status, list, switch, audit | connection and token check, accounts you can reach, switch the active account, read the audit trail | | google_ads_report | campaign_performance, impression_share, asset_group, gaql, metadata | curated campaign report, Search impression share, Performance Max asset-group performance, raw GAQL, and field discovery | | google_ads_campaign | create, update, status, budget, bidding, targeting | create any campaign type, rename and set dates and networks, pause and resume, budgets, bidding, and location/language/schedule targeting | | google_ads_ad_group | create, update, status, list_ads, add_ad, ad_status | manage ad groups and their ads, including per-channel ad builders via ad_type | | google_ads_keyword | list, add, update | list with quality score, add positive or negative, change bid or status | | google_ads_pmax | create_asset_group, asset_group, add_images, list_assets, remove_asset | create an asset group from text and images (images are required up front and it starts paused), update or delete a group, add images, list and remove assets | | google_ads_lookup | location, language | turn a location or language name into the numeric id that targeting and geo reports need |

A few things worth knowing: ROAS is computed as conversion value over cost. Average Position is gone (Google removed it), so use impression_share. Performance Max has no ad-level reporting, so use gaql on its asset groups.

Coverage

| | | |---|---| | Google Ads API version | v24.1 (via google-ads-api, Opteo) | | Coverage model | Curated actions for the common workflows, plus raw GAQL over every non-sensitive report resource. Not a 1:1 mapping of the ~100 API services. | | Write safety | Preview-first, yes/ok confirmation, PAUSED creates, durable audit log (see Money and safety). |

Big reports and pagination

Reports are bounded per response and paged without hitting Google again:

1. The first call fetches one bounded page and asks Google for the true total row count in the same request, so a capped report reads top 200 of 47,310 instead of quietly cutting off.
2. Leftover rows are parked in a short-lived (about 5 minutes), per-account cache.
3. If more rows remain, the reply ends with a cursor. The model asks whether you want the rest, then continues from cache with zero extra Google calls, so paging can't cause rate limiting.

One report run is bounded to limit rows by design. To go wider, tighten the query or aggregate in GAQL. For genuinely huge extracts, use an export rather than inline rows.

Scheduled and unattended use

Reporting is read-only and retried, so it's reliable for cron and scheduled jobs once the OAuth app is In Production.

• A dead refresh token returns a clear "reconnect Google Ads" message and is written to the audit log with category:"auth", so you can alert on it.
• Call google_ads_account with status at the start of a routine to fail fast.
• Quota and rate errors are retried with backoff, and if they still fail you get a clear "needs Standard Access" message.

Troubleshooting

| Symptom | What to try | |---------|-------------| | Refresh token dies after ~7 days | OAuth app is still in Testing. Publish it to In Production. | | PERMISSION_DENIED / "set login-customer-id" | GOOGLE_ADS_LOGIN_CUSTOMER_ID is only for reaching a client through a manager. For an account you access directly (it shows as [client] in account list), leave it empty. Setting a manager you do not reach that client through, or setting one at all when none is needed, causes this error. If it is still denied, the login genuinely lacks access to that customer id. | | unauthorized_client on token exchange | The refresh token was minted by a different OAuth client than GOOGLE_OAUTH_CLIENT_ID. Re-mint it with that exact client (in the OAuth Playground, check "Use your own OAuth credentials" first). | | Quota / rate errors | Developer token may need Standard Access. Reads are retried with backoff. | | "user_confirmation" / confirmed rejected | Call once without confirmed to preview, ask the user to type yes or ok, then re-call with confirmed:true and user_confirmation:"yes" (or "ok"). | | "not connected" / reconnect message | Refresh token revoked; re-auth (HTTP) or mint a new refresh token (stdio). | | HTTP container exits on boot | Missing TOKEN_ENC_KEY, PUBLIC_BASE_URL, or ALLOWED_REDIRECT_ORIGINS. Check logs. | | OAuth works but LibreChat never connects | Set requiresOAuth: true and startup: false on the MCP entry, add the host to allowedDomains, and point url at the public /mcp path. | | LibreChat logs OAuth not supported in unauthenticated discovery or repeated Reinspection failed ... timeout | Missing requiresOAuth: true. LibreChat is probing the server without auth to list tools, which always fails on an OAuth server. The flag silences the probe and shows the sign-in prompt directly. | | Stale connection after changing the server URL under the same name | LibreChat caches OAuth tokens per server name. Reconnect, or clear its cached tokens for that server, so it registers fresh against the new backend. | | Google returns redirect_uri_mismatch mid sign-in | PUBLIC_BASE_URL/auth/callback is not registered on the OAuth client. For localhost that is http://localhost:3001/auth/callback. |

Notes

• The underlying client, google-ads-api (Opteo), is the community Node library for the advertiser API; Google doesn't ship an official one. It targets API v24.1. The high-level query and mutate calls used here are version-agnostic, but check method signatures if you upgrade the library.
• Error messages and tool text are in English.
• See SECURITY.md for disclosure, residual risk, and key-compromise playbook. See CHANGELOG.md for release notes.

Acknowledgments

This project is built on google-ads-api, the community Node client for the Google Ads API maintained by the team at Opteo. Google ships no official Node library for the advertiser API, and Opteo's package fills that gap with a well-typed, carefully maintained interface that handles the hard parts (OAuth, GAQL, mutates, and the Google Ads protobufs) so this server does not have to. A sincere thank you to the Opteo maintainers and contributors: this MCP server stands on their work.

Disclaimer

This is an unofficial Google Ads API integration. It is not affiliated with, endorsed by, or supported by Google. "Google Ads" is a trademark of Google LLC. You are responsible for your account and any spend; use it within Google's API Terms of Service.

License

MIT

Contributing

See CONTRIBUTING.md.