Google Ads MCP Server: Setup Guide (May 2026)

On 28 April 2026, Google open-sourced the official Google Ads MCP server. For shopping feed teams it’s the missing half of the agent workflow: ad performance data flowing to your agent in the same conversation where it’s making feed decisions. This is the practical setup guide.

What the official Google Ads MCP actually does

The server (googleads/google-ads-mcp on GitHub) exposes two tools to any MCP-compatible client:

• list_accessible_customers, returns the Google Ads accounts you have access to under your authenticated MCC.
• search, runs an arbitrary GAQL (Google Ads Query Language) query against an account and returns the result set as JSON.

That’s the whole API surface. It’s intentionally narrow because Google released it as a read-only diagnostic and reporting layer. Mutations (changing bids, pausing campaigns, creating assets) still require direct calls to the Google Ads REST or gRPC API.

For shopping feed work this is actually the right scope. The expensive operations you want an agent to do, analyse performance, surface underperformers, recommend feed changes, are reads. The writes (changing the catalog, updating titles, pushing supplemental feeds) are better handled by a feed manager with its own API, not the Ads platform itself.

Setup: from clone to first query in 15 minutes

Prerequisites

• Python 3.10 or higher
• A Google Ads Manager account (MCC) with at least one linked account
• A Google Cloud project (for OAuth credentials)
• An MCP-compatible client (Claude Desktop is easiest; Cursor, Continue, and others also work)

Step 1: Clone the repository

git clone https://github.com/googleads/google-ads-mcp
cd google-ads-mcp
pip install -e .

Step 2: Get a Google Ads developer token

In Google Ads, go to Tools > API Center. If you’ve never used the API, you’ll need to apply for a developer token. Test-account tokens are granted instantly. Production tokens require a manual review by Google (typically 1-2 weeks; you’ll need to describe your use case and confirm you’ll respect the API terms).

For first-time setup, request a test token. You can swap to production later without changing the MCP server config.

Step 3: Create OAuth credentials

Google Cloud Console > APIs & Services > Credentials > Create credentials > OAuth client ID. Choose “Desktop application” as the type. Download the client_secret.json file.

The first time you run the server, it will open a browser window to complete the OAuth flow. After you approve, you’ll get a refresh token that the server can use indefinitely (until you revoke).

Step 4: Set environment variables

The server reads its config from environment variables:

export GOOGLE_ADS_DEVELOPER_TOKEN="your-22-char-token"
export GOOGLE_ADS_CLIENT_ID="your-oauth-client-id.apps.googleusercontent.com"
export GOOGLE_ADS_CLIENT_SECRET="your-oauth-client-secret"
export GOOGLE_ADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"  # Your MCC ID without hyphens

For local development, put these in a .env file. The repo includes a .env.example you can copy.

Step 5: Register with Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows. Add the server to the mcpServers block:

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "google_ads_mcp.server"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CLIENT_ID": "your-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Restart Claude Desktop. In a new conversation, ask “What Google Ads accounts can you access?”, Claude should call list_accessible_customers and return the list.

First useful queries

The search tool takes a GAQL query and a customer ID. Here are queries that justify the setup time on day one:

Top spending product groups, last 30 days

SELECT
  segments.product_item_id,
  segments.product_title,
  metrics.cost_micros,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions
FROM shopping_performance_view
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
LIMIT 100

Drop this into a Claude conversation as: “Use the Google Ads search tool to find the top 100 spending products in the last 30 days for account 1234567890, then group by conversion rate quartile.”

Disapproved products from the Ads side

Merchant Centre disapprovals are visible from Google Ads too:

SELECT
  segments.product_item_id,
  segments.product_title,
  segments.product_status
FROM shopping_performance_view
WHERE segments.product_status IN ('DISAPPROVED', 'PENDING_REVIEW')
  AND segments.date DURING LAST_7_DAYS

Pair this with your feed manager’s products.update tool and an agent can fix disapproved SKUs in the same conversation it discovered them.

Search term mining for negative keywords

SELECT
  search_term_view.search_term,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM search_term_view
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.advertising_channel_type = 'SHOPPING'
ORDER BY metrics.cost_micros DESC
LIMIT 200

An agent can run this, identify zero-conversion search terms with significant spend, and either suggest negatives or call out a feed title issue causing irrelevant matches.

Pairing Google Ads MCP with AI Shopping Feeds

The two-server pattern is where the real workflow value sits. Google Ads MCP brings the performance data; AI Shopping Feeds brings the catalog control.

{
  "mcpServers": {
    "google-ads": { "...": "as above" },
    "ai-shopping-feeds": {
      "command": "npx",
      "args": ["@aishoppingfeeds/mcp"],
      "env": {
        "AISHOPPINGFEEDS_API_KEY": "your-api-key"
      }
    }
  }
}

With both registered, agent prompts like this become single-conversation jobs:

“Find Shopping products in account 1234567890 with cost > $50 and zero conversions in the last 14 days. For each one, look up the current title in the AI Shopping Feeds catalog, rewrite the title for higher relevance, and queue the changes as a supplemental feed.”

The agent reads from Google Ads via the MCP, writes to AI Shopping Feeds via its MCP, and the feed manager handles the Merchant Centre push. No glue code, no scheduled scripts, no spreadsheet exports.

Read-only is a feature, not a limitation

The MCP-only-reads decision is often framed as a gap, but for shopping feed work it’s the right boundary:

• Performance reads are safe to run autonomously
• Feed mutations are safer in a system designed for catalog state management
• Bid and budget mutations are still high-stakes enough to belong in the Ads UI or scripts with review

Future iterations of the Google Ads MCP will likely add mutation tools. Until then, the read+report layer is enough to drive most agent-led optimisation loops.

What can go wrong

Developer token still in test mode. Test tokens are limited to test accounts. If you point the MCP at a production MCC with a test token, every query returns an error. Apply for standard access early.

Refresh token expires. Refresh tokens don’t expire by default but can be revoked by Google if unused for 6 months, or if the user changes password, or if the OAuth scope changes. If the server starts returning auth errors, re-run the refresh-token helper.

MCC vs operating account mix-up. GOOGLE_ADS_LOGIN_CUSTOMER_ID should be your MCC ID. The customer ID you pass in queries should be the operating account ID. Mixing these up causes AUTHENTICATION_ERROR results that are easy to misdiagnose.

Rate limits on the search tool. The Google Ads API enforces query-volume limits per developer token. Heavy agent use (one user, multiple parallel agents) can hit these. The official server doesn’t implement caching by default, add a small local cache if you’re hitting limits.

What’s coming

Google has indicated more tools will arrive over the next few releases. Likely candidates: campaign-level mutations (pause, budget changes), asset uploads, and conversion-import endpoints. The MCP spec also allows progress events, so long-running operations (bulk uploads, large GAQL pulls) can stream results back to the client.

For now, the read-only MCP plus a write-capable feed manager covers most of the shopping-ad optimisation loop without writing a single integration line.

Sources

• Google Ads MCP server, developer documentation
• googleads/google-ads-mcp on GitHub
• Google Ads API, GAQL reference
• Model Context Protocol specification
• Related read: Google Ads, Merchant Center, and product feeds