ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Connect Google Ads to an MCP Server

Connect Google Ads to an MCP server with Google’s read-only bridge, OAuth, customer IDs, local stdio, or Cloud Run deployment.

By the ScreenshotNeo team1 October 20269 min read

Use Google’s official Google Ads MCP server as the bridge between your MCP client and the Google Ads API. Run it locally over stdio for one developer workstation, or deploy it to Cloud Run when several clients need a shared HTTP/SSE endpoint. You still need a Google Cloud project, Google Ads account access, and OAuth 2.0 or application-default credentials.

The documented implementation is read-only. It can discover accessible customers, inspect resource metadata, and run Google Ads Query Language (GAQL) searches, but it cannot change bids, pause campaigns, or create assets.

Architecture at a glance

The request path is:

  1. Your MCP client (such as Claude, Cursor, or another MCP host) discovers the server’s tools.
  2. The Google Ads MCP server authenticates to Google Ads API.
  3. The server executes a read-only operation such as a GAQL search.
  4. Structured results return to the model, which summarizes them.

MCP is the protocol layer; it does not grant Google Ads access by itself. The Google Ads account and Cloud project still control authorization. See Google’s Google Ads API documentation for API prerequisites.

Prerequisites

  • A Google Cloud project that you can administer.
  • The Google Ads API enabled in that project.
  • Access to the Google Ads client account you want to query.
  • The account’s 10-digit customer ID.
  • One authentication method: OAuth 2.0 client credentials, or application-default credentials such as a service account.
  • An MCP host that supports a local stdio process or a remote HTTP/SSE server.

The Google Ads OAuth scope is https://www.googleapis.com/auth/adwords. Older tutorials may also ask for a developer token. Google’s current policy says, “We sunset developer tokens on September 9, 2026.” Access levels are now associated with the Google Cloud project; existing developer-token headers may remain in code but are optional and ignored. Check the current developer-token policy before copying an older setup.

Step 1: Create and configure the Cloud project

  1. Open Google Cloud Console and create or select a project.
  2. Enable the Google Ads API for that project.
  3. Check the project’s API access level and resolve any access request shown by Google.
  4. Create OAuth client credentials if you will use an interactive user login.
  5. For a workload identity, configure application-default credentials or a service account and grant that identity access to the Google Ads account.

Keep client secrets outside source control. For local work, use your MCP host’s environment-variable support or a secret manager. For Cloud Run, use Secret Manager or runtime environment configuration rather than baking credentials into an image.

Step 2: Choose authentication

OAuth 2.0 user credentials

Use OAuth when a person should consent to access and the MCP server represents that person’s Google Ads permissions. Configure the OAuth client, authorize the adwords scope, and store the resulting refresh-token material where only the server process can read it. The exact consent and redirect steps depend on your MCP host.

Application-default or service-account credentials

Use application-default credentials for a controlled local or Cloud Run workload. The service account must be granted access to the relevant Google Ads account. This avoids an interactive login at runtime, but makes service-account key management and account sharing part of your operational responsibility.

Manager accounts and login customer ID

If a manager account is used to reach a client account, set GOOGLE_ADS_LOGIN_CUSTOMER_ID to the manager’s 10-digit ID with no hyphens. The target client’s 10-digit customer ID is supplied to searches or discovered with the accessible-customers tool. Google’s API requests also use an OAuth bearer token and may include a login-customer-id header for manager access; follow the current call-structure documentation.

Step 3: Run the MCP server locally over stdio

Local stdio is the shortest path when one MCP host runs on your workstation. Obtain the official Google Ads MCP server source and install its documented Python dependencies, then provide credentials and account settings through environment variables. The exact entry-point command is release-specific, so use the command documented by Google for the version you install.

# Shell example: names shown here are configuration values, not secrets
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"  # only when using a manager account
export GOOGLE_ADS_CUSTOMER_ID="0987654321"         # target client, if your host uses this variable
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/credentials/service-account.json"

# Start the official server command from the release you installed.
# Example placeholder form:
python -m google_ads_mcp_server

Add the same command and environment to your MCP host configuration. A generic stdio entry looks like this:

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "google_ads_mcp_server"],
      "env": {
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_CUSTOMER_ID": "0987654321",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/credentials.json"
      }
    }
  }
}

Replace the module name and variable names with those in the official release instructions. Do not paste a private key into a chat prompt or commit it to this JSON file.

Step 4: Verify access with safe queries

Start with discovery and metadata before requesting performance data:

  1. Ask: “What customers do I have access to?” This checks account authorization.
  2. Ask: “Show the available fields for campaign resources.” This checks metadata discovery.
  3. Ask for a small, bounded GAQL query, such as active campaign names and statuses.
  4. Only then request date-ranged metrics such as impressions, clicks, cost, and conversions.

Useful prompts include:

What customers do I have access to?
How many active campaigns do I have?
Show campaign name, status, impressions, clicks, and cost for the last 7 days.
Compare this week's campaign performance with the previous week.
Which campaigns have zero impressions in the last 24 hours?

Review the returned customer ID and date range before relying on a summary. Natural-language requests can be ambiguous; ask the model to show the GAQL fields and filters it used when the result matters.

Step 5: Deploy a shared server on Cloud Run

Choose Cloud Run when multiple MCP clients need one endpoint or when the server should run away from a developer laptop. Google’s documented deployment uses an HTTP/SSE transport and exposes the server’s /mcp endpoint. The practical sequence is:

  1. Build the official server container from its release instructions.
  2. Push the image to a container registry.
  3. Deploy it to Cloud Run in the region you choose.
  4. Configure the OAuth client, base URL, and allowed host settings required by the server.
  5. Store credentials in Secret Manager or equivalent runtime configuration.
  6. Point each MCP client at the deployed /mcp endpoint and complete its authentication flow.
# Illustrative Cloud Run shape; use the image and flags from Google's release guide.
gcloud run deploy google-ads-mcp \
  --image REGION-docker.pkg.dev/PROJECT/REPOSITORY/google-ads-mcp:TAG \
  --region REGION \
  --set-env-vars GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \
  --allow-unauthenticated

The final authentication posture depends on your client and OAuth design. If the endpoint is publicly reachable, require the server’s supported OAuth protection and limit who can complete consent. If your organization uses an identity-aware proxy or private ingress, configure that in addition to the MCP server’s own requirements.

Local stdio or Cloud Run?

Decision Local stdio Cloud Run HTTP/SSE
Deployment location Developer workstation Managed Google Cloud service
Best for One MCP host and quick setup Several clients or a shared endpoint
Credential handling Local files or environment Runtime secrets and service identity
Network exposure No public listener required Endpoint protection and host configuration required
Maintenance Each workstation updates its copy One container version to patch and deploy

This recommendation follows the transports and deployment procedures documented for the server: stdio minimizes setup for a single host, while Cloud Run centralizes a remotely reachable service.

GAQL patterns that work well with an MCP assistant

Ask for narrow queries first. A campaign status query can be expressed as:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
WHERE campaign.status != 'REMOVED'
ORDER BY campaign.name

A date-ranged performance request can use:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status = 'ENABLED'

Field availability and compatible segments vary by resource. Use get_resource_metadata before composing a complex query, and have the assistant report when a metric is unavailable instead of substituting a different field.

Security and reliability checklist

  • Use the smallest Google Ads account scope that answers the question.
  • Keep OAuth refresh tokens and service-account keys in a secret store.
  • Do not put credentials in MCP prompts, logs, Git repositories, or container layers.
  • Use a separate Cloud project for production workloads when audit boundaries require it.
  • Log request identity, customer ID, query purpose, and result status without logging access tokens.
  • Bound date ranges and row counts to avoid expensive or slow searches.
  • Have a human review financial conclusions before acting on them.
  • Remember that this MCP implementation is read-only; campaign changes require a separate approved workflow.

Troubleshooting

Symptom Likely cause Fix
No customers returned The OAuth identity or service account has no Google Ads access. Grant the identity access, re-authorize the OAuth scope, and run customer discovery again.
Manager account cannot reach a client The login customer ID is missing, formatted with hyphens, or points at the wrong manager. Set GOOGLE_ADS_LOGIN_CUSTOMER_ID to the manager’s 10-digit ID without hyphens.
Invalid credentials Expired OAuth material, wrong credential path, or unavailable application-default credentials. Re-authorize OAuth or verify GOOGLE_APPLICATION_CREDENTIALS and the runtime identity.
Permission denied The account, project, or API access level does not authorize the request. Check Cloud project API access, Google Ads account sharing, and the selected customer ID.
GAQL field error The field is incompatible with the selected resource or segments. Inspect resource metadata and reduce the query to supported fields.
Local MCP client shows no tools The command exits immediately or writes non-protocol output to stdout. Run the server directly, inspect stderr, verify dependencies, and keep diagnostic logging off stdout.
Cloud Run callback or connection fails Base URL, OAuth redirect, host, or /mcp endpoint is misconfigured. Use the deployed HTTPS base URL exactly in the OAuth and MCP settings, then verify the endpoint path.
Results are slow or truncated The query requests too many rows or a broad date range. Filter by date and status, request only needed fields, and paginate or summarize in smaller calls.
A tutorial asks for a developer token The tutorial predates the 2026 policy change. Follow the current project access guidance; developer-token headers are now optional and ignored after the sunset date.

Performance, reliability, and cost considerations

  • Query size: Smaller GAQL projections and bounded date ranges reduce latency and make model summaries more reliable.
  • Cold starts: Cloud Run may start a new container after idle periods. Keep initialization lightweight and set a request timeout appropriate for the MCP server.
  • Retries: Retry transient transport failures with backoff, but do not blindly repeat a query that may have failed because of permissions or invalid GAQL.
  • Caching: Cache metadata and stable customer lists briefly; fetch performance metrics for the requested date range so reports do not become stale.
  • Cost: Google Cloud charges for the Cloud Run resources you consume under your account. Google Ads API access and MCP server behavior are separate from any model-provider charges.
  • Read-only boundary: Because the documented server cannot mutate campaigns, it is appropriate for reporting and investigation. Use a separately reviewed system for bid or asset changes.

Or skip the browser setup

If your next step is turning a Google Ads report or landing page into an image, ScreenshotNeo provides a single screenshot request instead of maintaining browser automation. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and response headers identify the page verdict and billing result. Its MCP server also lets AI agents take screenshots through take_screenshot, get_page_info, and capture_pdf.

See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo includes 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Can the MCP server pause a campaign?

No. The documented implementation is strictly read-only and cannot modify bids, pause campaigns, or create assets.

Do I need a manager account?

No. A direct client-account identity is enough. A manager account is useful when one identity needs access to several client accounts.

Which customer ID belongs in the configuration?

Use the 10-digit client customer ID for the account you query. Set the manager’s 10-digit ID as GOOGLE_ADS_LOGIN_CUSTOMER_ID when accessing that client through a manager.

Is Cloud Run required?

No. Local stdio is the simplest deployment for one MCP host. Cloud Run is useful when multiple clients need a shared remote endpoint.

Why do older setup guides mention developer tokens?

Google changed the policy in 2026 and sunset developer tokens on September 9, 2026. Follow the current Cloud-project access guidance.

Keep reading