Connect Google Ads to Claude, ChatGPT and Copilot: campaigns, ad groups, ads, keywords, search terms, budgets, conversion actions and change history as MCP tools. Powered by AnythingMCP.
Google Ads MCP Server gives Claude, ChatGPT, Copilot and Cursor 17 tools for Google Ads: campaigns, ad groups, ads, keywords, search terms, budgets, conversion actions and change history. Every tool only reads. It runs on AnythingMCP: one click on AnythingMCP Cloud, or self-hosted with Docker. Credentials are stored encrypted and every call is audited.
Last verified: 2026-09-27 against two production Google Ads accounts (API v25, Explorer access) (all 17 tools and the 15 playbook queries called live, the connector authorized on AnythingMCP Cloud, and an account review run from claude.ai).
Adapter synced: 2026-09-27
Maintained by @keysersoft, an AnythingMCP maintainer. Built on AnythingMCP by helpcode.ai.
- Sign in at cloud.anythingmcp.com and open the install link.
- Enter
GOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET(see Authentication). - Copy the URL of your MCP server under MCP Servers and add it to your AI client (below).
AnythingMCP Cloud is the same open-source code, operated by helpcode.ai in Frankfurt, Germany.
Needs Docker 24+, openssl and Node 18+.
git clone https://github.com/keysersoft/google-ads-mcp-server.git
cd google-ads-mcp-server
./scripts/install.shinstall.sh writes .env with fresh secrets, starts AnythingMCP, creates the first admin, installs the connector if GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set in .env and creates an MCP API key. Without credentials it prints the install link instead: http://localhost:3000/connectors/store?install=google-ads. Then check the whole chain:
npm install && node scripts/smoke.mjs-
Claude (claude.ai, Desktop, mobile): Customize → Connectors → Add custom connector, paste your MCP server URL and sign in. Claude connects from Anthropic's cloud, so the URL must be public HTTPS: your AnythingMCP Cloud URL, or your own instance behind TLS.
-
Claude Code:
claude mcp add --transport http google-ads-mcp-server http://localhost:4000/mcp --header "X-API-Key: <MCP_API_KEY>" -
Cursor (
.cursor/mcp.json) and VS Code / GitHub Copilot (.vscode/mcp.json, keyserversinstead ofmcpServers, plus"type": "http"):{ "mcpServers": { "google-ads-mcp-server": { "url": "http://localhost:4000/mcp", "headers": { "X-API-Key": "<MCP_API_KEY>" } } } } -
ChatGPT: add the public HTTPS URL as a connector (app) in ChatGPT's settings. A
localhostURL does not work there.
17 tools, generated from adapter/google-ads.json. read tools cannot change anything in the source system.
| Tool | What it does | Access |
|---|---|---|
gads_playbook |
START HERE for any Google Ads question: returns, with NO API call, a router from common questions (account health, wasted spend, search-term mining, Quality… | read |
gads_list_accessible_customers |
List the Google Ads accounts the authorised Google user can access directly, as resource names ('customers/1234567890'). | read |
gads_get_customer |
Read one Google Ads account's settings: name, currency, time zone (all dates in reports are in this zone), whether it is a manager (MCC) or test account,… | read |
gads_list_client_accounts |
List the accounts under a manager (MCC) account: id, name, depth in the hierarchy, whether each is itself a manager, currency, time zone and status. | read |
gads_run_gaql |
Run any read-only Google Ads Query Language (GAQL) query against one account: every resource, attribute, segment and metric of the Google Ads API. | read |
gads_query_field_catalog |
Look up Google Ads API field metadata (names, category RESOURCE/ATTRIBUTE/SEGMENT/METRIC, data type, enum values, whether selectable, filterable, sortable). | read |
gads_account_daily_metrics |
Account-level totals per day for a date range: impressions, clicks, cost, conversions, conversion value. | read |
gads_list_campaigns |
List the account's campaigns (removed ones excluded) with status, serving status, primary status and its reasons (why a campaign is limited or not serving),… | read |
gads_campaign_performance |
Campaign performance totals for a date range, one row per campaign, sorted by cost: impressions, clicks, CTR, average CPC, cost, conversions, conversion… | read |
gads_ad_group_performance |
Ad group performance totals for a date range, one row per ad group with its campaign, sorted by cost. | read |
gads_ad_performance |
Ad performance for a date range with the ad itself: type, final URLs, responsive search ad headlines and descriptions, ad strength and policy approval status. | read |
gads_keyword_performance |
Keyword performance for a date range with match type, status and Quality Score components (quality score 1-10, expected CTR, ad relevance, landing page… | read |
gads_search_terms |
The search terms report: what people actually typed before your Search ads showed, with campaign, ad group, whether the term is already added or excluded,… | read |
gads_budget_pacing |
Enabled campaigns with their daily budget, spend in the date range and Search impression share lost to budget and to rank. | read |
gads_conversion_actions |
List the account's conversion actions (removed ones excluded): name, type, source, category, status, whether each is a primary goal, counting (one vs… | read |
gads_change_history |
Who changed what in the account and when: timestamp, user email, tool used (web UI, API, scripts, Editor), resource type and name, operation and the changed… | read |
gads_recommendations |
Google's current optimisation recommendations for the account (budget, bidding, keywords, ads, assets...) with the campaign they apply to and the estimated… | read |
- How did my Google Ads account do in the last 30 days? Spend, conversions, cost per conversion and the main campaigns.
- Compare this month with last month by campaign: spend, conversions, CPA and ROAS.
- List the search terms from the last 30 days that cost money and never converted, and group them into negative keyword ideas.
- Which keywords have a Quality Score of 5 or lower, and which component is below average?
- Are my Search campaigns losing impression share to budget or to rank?
- Which ads are disapproved or have poor ad strength?
More in examples/prompts.md.
The connector signs in with OAuth 2.0 as a Google user. You need an OAuth client from a Google Cloud project that has Google Ads API access:
| Variable | Where to find it |
|---|---|
GOOGLE_CLIENT_ID |
Google Cloud console → APIs & Services → Credentials → OAuth client ID (type Web application) |
GOOGLE_CLIENT_SECRET |
the same OAuth client |
GOOGLE_ADS_LOGIN_CUSTOMER_ID (optional) |
the 10-digit id of the manager (MCC) account, only when you reach client accounts through a manager |
- Enable Google Ads API in the project and check its access level on the project's Google Ads API page. A new project starts at Test (test accounts only); request Explorer to read real accounts. Since 9 September 2026 no developer token is needed.
- Add the redirect URI
<your AnythingMCP URL>/api/mcp-oauth/callbackto the OAuth client (on AnythingMCP Cloud:https://cloud.anythingmcp.com/api/mcp-oauth/callback), and set the OAuth consent screen to In production so the refresh token does not expire after 7 days. - Install the connector with the client ID and secret, then click Authorize with Provider on the connector page. The refresh token is stored encrypted and access tokens are renewed automatically.
Google Ads has a single OAuth scope (adwords) and it is not read-only. The connector exposes only read tools; authorizing a Google Ads user with the Read only role adds a second safeguard.
- Read or write is your choice. All 17 tools only read. Assign the connector to an MCP server whose role whitelists only the tools you want, and the rest are invisible to that client.
- Credentials are encrypted with AES-256-GCM and never shown to the model.
- Response mapping drops or reshapes fields per tool before they reach the model, e.g. bank details or personal data.
- Audit log: every call is recorded with input, output, duration and status, in your own database when self-hosted.
- SSO, RBAC and SCIM are included in the self-hosted build.
No. Google retired developer tokens on 9 September 2026. API access now depends on the access level of your Google Cloud project: Test reaches only test accounts, Explorer (2,880 operations a day) reads real accounts, Basic and Standard raise the quota.
Install the Google Ads connector on AnythingMCP, authorize it once in the browser, then add the AnythingMCP server URL to Claude as a custom connector or to ChatGPT as a developer-mode app. Both sign in with OAuth, so nothing runs on your computer. Claude Code, Cursor and other clients use the same URL with an API key header.
No. All 17 tools read: reports, lists and GAQL queries. There is no tool to pause, create or edit anything, and every tool is annotated as read-only for the client.
Account settings and manager hierarchies, daily account metrics, campaign, ad group, ad and keyword performance with Quality Score components, the search terms report, budget pacing with impression share lost to budget and rank, conversion actions, change history and recommendations. Anything else goes through gads_run_gaql, and gads_playbook gives the model tested queries for device, location, hour, landing page, Performance Max, asset and audience reports.
Yes. Set GOOGLE_ADS_LOGIN_CUSTOMER_ID to the manager's id; gads_list_client_accounts lists the accounts below it.
A report is one operation. Answering a question usually takes 2 to 8 calls, well inside the 2,880 operations a day of Explorer access. The quota belongs to the Cloud project, so connectors sharing one OAuth client share it.
| Problem | Fix |
|---|---|
401 / 403 from the vendor |
The credentials are wrong or lack rights. Re-enter them on the connector page; the import runs a test call and shows the result. |
| Tools missing in the AI client | The connector is not assigned to the MCP server the client uses. Check MCP Servers, then run node scripts/smoke.mjs. |
| The host is on your internal network | Self-host AnythingMCP on that network and add the hostname to SSRF_ALLOWED_HOSTS, or the outbound guard blocks the call. |
| Works locally, fails on AnythingMCP Cloud | The system must be reachable from the internet with a valid TLS certificate. |
| Symptom | Cause and fix |
CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION |
The Cloud project behind the OAuth client still has Test access. Request Explorer access on the project's Google Ads API page. |
USER_PERMISSION_DENIED on a client account |
You reach the account through a manager: set GOOGLE_ADS_LOGIN_CUSTOMER_ID to that manager's id, or authorize a user with direct access. |
401 or invalid_grant |
The refresh token was revoked or expired (an OAuth consent screen in Testing expires it after 7 days). Set the consent screen to In production and click Authorize with Provider again. |
UNRECOGNIZED_FIELD or PROHIBITED_* from gads_run_gaql |
A field name is wrong or does not combine with the resource. Check it with gads_query_field_catalog. |
RESOURCE_EXHAUSTED |
The daily or per-minute quota of the Cloud project is used up. Wait, or request a higher access level. |
| Campaign rows with zero metrics | Paused or idle campaigns are returned too and sort last; they are not an error. |
| Amounts look a million times too large | Money fields are in micros of the account currency: divide by 1,000,000. |
- openapi-to-mcp: OpenAPI to MCP: turn any OpenAPI/Swagger or REST API into an MCP server for Claude & ChatGPT. Every endpoint a tool, no code.
- jev-mcp-server: Jev MCP server: use TypeSafe Jev in Claude & ChatGPT. Yes/no, classification and scoring with probabilities, hosted or self-hosted.
- AnythingMCP: the open-source MCP server and gateway this repository is built on.
AGPL-3.0-only. The adapter definition in adapter/ comes from AnythingMCP (AGPL-3.0).