# 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.

```sh
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.

## 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.

```sh
.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](docs/merchant-shopping.md). 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`.