Google Ads MCP starter

Run your own MCP server with Google Ads read tools and optional approved Search campaign changes. Most users need only the Google Ads setup below. Merchant Center is a separate, optional integration and is disabled by default. Google Ads credentials do not configure Merchant Center access. This repository contains no shared credentials, account access, production configuration, or deployment history. All sample account IDs, product IDs, and customer names are fictional.

Install and test

Use Python 3.10 or newer.

python3 -m venv .venv
.venv/bin/pip install '.[dev]' pyfakefs
.venv/bin/python -m unittest discover -s tests -p '*_test.py'

The default tests use mocks and need no Google credentials. Optional LLM tests require your own Gemini credentials and can incur costs.

Related MCP server: Google Ads MCP

Configure Google Ads read access

1. Copy .env.example to a private .env file. Use your process manager or MCP client to inject its values. The server does not load dotenv files.

2. Obtain your own Google Ads developer token. Configure Application Default Credentials for an identity with Google Ads access and the https://www.googleapis.com/auth/adwords scope.

3. Set GOOGLE_ADS_MANAGER_ID to your ten-digit manager ID and GOOGLE_ADS_MANAGER_NAME to its exact name. Set GOOGLE_ADS_LOGIN_CUSTOMER_ID to your login manager ID.

4. Start the server with your configured environment.

.venv/bin/google-ads-mcp

Local mode uses stdio and trusts the local process environment. Keep credentials outside the repository and restrict access to the ledger.

Read tools do not require a policy file, approval key, ledger, Merchant account, or Merchant credentials. Campaign mutation tools are listed but refuse changes until their required policy and approval configuration exists.

Add governed Search campaign writes

1. Copy policy.example.json to policy.local.json. Replace the fictional customer identity, currency, time zone, domains, budget caps, conversion goals, and campaign allowlist. An empty campaign allowlist denies existing-campaign edits.

2. Set GOOGLE_ADS_MCP_ACCOUNT_POLICY_PATH, the runtime caller and approver identities, and your own random approval HMAC key of at least 32 bytes. Do not reuse the bearer token as this key.

3. Configure the ledger variables in .env.example and create its private directory with mkdir -p .runtime.

Campaign tools use prepare, validate-only, issue approval, apply with an idempotency key, and readback. New Search campaigns are created PAUSED. Existing-campaign edits support approved status changes and enforce account policy.

An authorization reference records your human approval. The gateway does not independently verify an external ticket or chat message. Decide which agents may issue approvals before giving them credentials.

Optional Merchant Center and Shopping feed tools

Skip this integration unless you need product feeds, item issues, supplemental title or custom-label overrides, or Merchant price reports. Follow the separate Merchant Center setup guide. It uses different account IDs, API registration, credentials, and permissions from Google Ads.

These tools manage Merchant Center product feeds and reports. They do not create Shopping or Performance Max campaigns. Campaign creation and mutation in this starter support Search campaigns only.

Run an authenticated HTTP service

Set GOOGLE_ADS_MCP_HTTP=true. Configure GOOGLE_ADS_MCP_BEARER_IDENTITIES_JSON as a JSON object mapping caller names to SHA-256 digests of independently generated high-entropy bearer tokens. Keep the original tokens private in your MCP clients.

Configure GOOGLE_ADS_MCP_FIRESTORE_PROJECT, GOOGLE_ADS_MCP_FIRESTORE_DATABASE, and a unique GOOGLE_ADS_MCP_FIRESTORE_NAMESPACE. The runtime identity needs Firestore access. Set GOOGLE_ADS_MCP_LEDGER_BACKEND=firestore for durable shared approval state. Serve /mcp behind HTTPS. Never expose the unauthenticated stdio configuration as a public HTTP service.

The Dockerfile builds the server but does not provision cloud infrastructure or secrets. Deploy into your own project.

License and attribution

Licensed under Apache 2.0. The Google Ads read-tool foundation retains Google LLC copyright notices. Scale Lean maintains the controlled campaign and Merchant extensions. See LICENSE and NOTICE.