Skip to content
Back to search

google-ads-mcp

This repo contains the source code for running an MCP server that interacts with the Google Ads API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/googleads/google-ads-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/googleads/google-ads-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/googleads--google-ads-mcp/badge.svg)](/listings/googleads--google-ads-mcp)

HTML

<a href="/listings/googleads--google-ads-mcp"><img src="/api/listings/googleads--google-ads-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Setup involves the following steps:

1. Configure Python. 1. Configure Developer Token. 1. Enable APIs in your project 1. Configure Credentials. 1. Configure your MCP client.

Configure Python

[Install pipx](https://pipx.pypa.io/stable/#install-pipx).

After a version has been published to PyPI, you can run that exact version instead of following the latest repository state:

pipx run --spec "google-ads-mcp==X.Y.Z" google-ads-mcp

Configure Developer Token (Optional)

If your setup requires a developer token, follow the instructions for [Obtaining a Developer Token](https://developers.google.com/google-ads/api/docs/get-started/dev-token).

Your developer token must have at least [Explorer access](https://developers.google.com/google-ads/api/docs/get-started/dev-token#access-levels) to query production accounts. New tokens may be automatically upgraded to Explorer access; if not, you can apply through the API Center. See the [access levels documentation](https://developers.google.com/google-ads/api/docs/get-started/dev-token#access-levels) for details.

If you see the error *"The developer token is only approved for use with test accounts"*, your token does not yet have access to production accounts. See the [access levels documentation](https://developers.google.com/google-ads/api/docs/access-levels) for how to request the access level you need.

Enable APIs in your project

[Follow the instructions](https://support.google.com/googleapi/answer/6158841) to enable the following APIs in your Google Cloud project:

* [Google Ads API](https://console.cloud.google.com/apis/library/googleads.googleapis.com)

Configure Credentials

Option 1: Using FastMCP OAuth Proxy

The server supports FastMCP's [OAuth proxy](https://gofastmcp.com/servers/auth/oauth-proxy) feature for dynamic user authentication. This is useful when running the server as a web service.

To enable it, set the following environment variables:

- `GOOGLE_ADS_MCP_OAUTH_CLIENT_ID`: Your Google Cloud OAuth 2.0 Client ID. - `GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET`: Your Google Cloud OAuth 2.0 Client Secret. - `GOOGLE_ADS_MCP_BASE_URL`: (Optional) The base URL where the server is accessible (defaults to `http://localhost:8080`). - `GOOGLE_ADS_MCP_JWT_SIGNING_KEY`: (Optional) Secret key used to sign FastMCP JWT tokens across multiple server instances or deployments. - `GOOGLE_ADS_MCP_STORAGE_TYPE`: (Optional) Storage backend for OAuth state (`filetree`, `redis`, `firestore`, or `memory`). - `GOOGLE_ADS_MCP_STORAGE_PATH`: (Optional) Directory path for `filetree` persistent storage. - `GOOGLE_ADS_MCP_STORAGE_REDIS_URL`: (Optional) Redis URL for `redis` persistent storage. - `GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT`: (Optional) Google Cloud project for `firestore` persistent storage. Defaults to the project inferred from Application Default Credentials. Setting it selects the `firestore` backend even if `GOOGLE_ADS_MCP_STORAGE_TYPE` is unset. - `GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE`: (Optional) Firestore database name for `firestore` persistent storage. Defaults to `(default)`. - `GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY`: (Optional) Encryption key for stored OAuth tokens. - `GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION`: (Optional) Set to `true` to disable token encryption.

The `redis` and `firestore` backends need their storage library installed alongside the server: `pip install py-key-value-aio[redis]` and `pip install google-ads-mcp[firestore]` respectively.

Once this is enabled, you can authenticate to the API through your MCP client.

When these variables are set, the server automatically switches to the `streamable-http` transport instead of `stdio`.

You will need to run the server as a separate process and configure your MCP client to connect to the Streamable HTTP endpoint (for example, `http://localhost:8080/mcp`).

Local WSL and Podman deployment

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 385 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Google Ads MCP Server
  2. An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that enables LLMs and AI agents to query and manage [Google Ads](https://developers.google.com/google-ads/api) accounts.
  3. ## Table of Contents
  4. - [Overview](#overview)
  5. - [Quickstart & Setup](#quickstart--setup)
  6. - [1. Prerequisites](#1-prerequisites)
  7. - [2. Choose an Authentication Mode](#2-choose-an-authentication-mode)
  8. - [3. Configure Your MCP Client](#3-configure-your-mcp-client)
  9. - [Tools & Resources](#tools--resources)
  10. - [Available Tools](#available-tools)
  11. - [Available Resources](#available-resources)
  12. - [Configuration & Security](#configuration--security)
  13. - [Propose & Confirm Safety Workflow](#propose--confirm-safety-workflow)
  14. - [Configuring and Namespacing Tools](#configuring-and-namespacing-tools)
  15. - [Tool Call Auditability](#tool-call-auditability)
  16. - [Environment Variables Reference](#environment-variables-reference)
  17. - [Deployment](#deployment)
  18. - [Local Container Deployment (Docker / Podman)](#local-container-deployment-docker--podman)
  19. - [Google Cloud Run Deployment](#google-cloud-run-deployment)
  20. - [Try It Out](#try-it-out)
  21. - [Contributing](#contributing)
  22. ## Overview
  23. The Google Ads MCP Server exposes [MCP Tools](https://modelcontextprotocol.io/docs/concepts/tools) and [MCP Resources](https://modelcontextprotocol.io/docs/concepts/resources) backed by the [Google Ads API](https://developers.google.com/google-ads/api/reference/rpc/latest/overview). It supports:
  24. - **Read & reporting workflows**: GAQL queries, accessible customer discovery, resource field metadata, and API reference resources.
  25. - **Guarded account mutations**: Asset creation, video uploads, and label management protected by a two-step **Propose & Confirm** workflow.
  26. - **Flexible deployment**: Run locally over `stdio` with Application Default Credentials, or over **Streamable HTTP** with FastMCP's OAuth proxy and structured audit logging.
  27. > **Notes:**
  28. > - Connecting an LLM or agent to this server exposes your accessible Google Ads account data to that client.
  29. > - API calls made by this server include an MCP telemetry header used by Google to collect usage statistics and improve the product.
  30. > - Report bugs or feature requests on the [GitHub issue tracker](https://github.com/googleads/google-ads-mcp/issues).
  31. ---
  32. ## Quickstart & Setup
  33. ### 1. Prerequisites
  34. 1. **Python & `pipx`** (for local non-container setups): Python 3.11+ and [`pipx`](https://pipx.pypa.io/stable/#install-pipx).
  35. To run a specific released version from PyPI:
  36. ```shell
  37. pipx run --spec "google-ads-mcp==X.Y.Z" google-ads-mcp
  38. ```
  39. 2. **Google Cloud Project**: Enable the [Google Ads API](https://console.cloud.google.com/apis/library/googleads.googleapis.com) in your Google Cloud project ([how to enable APIs](https://support.google.com/googleapi/answer/6158841)).
  40. ### 2. Choose an Authentication Mode
  41. The server supports two authentication and transport modes out of the box:
  42. | Mode | Transport | Best For |
  43. | :--- | :--- | :--- |
  44. | **Mode A: Application Default Credentials (ADC)** | `stdio` | Single-user local CLI/IDE agents where the MCP client spawns the server directly. |
  45. | **Mode B: FastMCP OAuth Proxy** | `streamable-http` | Shared/remote deployments or local containers where server credentials stay isolated from MCP client configs. |
  46. #### Mode A: Local `stdio` with Application Default Credentials (ADC)
  47. Configure [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc) for a user or service account with access to your Google Ads accounts. Credentials must include the Google Ads API scope (`https://www.googleapis.com/auth/adwords`). See [Manage OAuth Clients](https://support.google.com/cloud/answer/15549257) if you need to create an OAuth desktop or web client first.
  48. - **Option 1 — User credentials with an OAuth client JSON file:**
  49. ```shell
  50. gcloud auth application-default login \
  51. --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  52. --client-id-file=YOUR_CLIENT_JSON_FILE
  53. ```
  54. - **Option 2 — Service account impersonation:**
  55. ```shell
  56. gcloud auth application-default login \
  57. --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  58. --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform
  59. ```
  60. When the command finishes, note the credentials path printed to the console (`Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]`) for your MCP client configuration.
  61. #### Mode B: Streamable HTTP with FastMCP OAuth Proxy
  62. Setting `GOOGLE_ADS_MCP_OAUTH_CLIENT_ID` and `GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET` enables FastMCP's [OAuth proxy](https://gofastmcp.com/servers/auth/oauth-proxy) for dynamic per-user Google OAuth login and automatically switches the server transport from `stdio` to `streamable-http` (default endpoint: `http://localhost:8080/mcp`).
  63. Run the server as a standalone process or container (see [Deployment](#deployment) and [Environment Variables Reference](#environment-variables-reference)), then point your MCP client at the HTTP endpoint—no server secrets are stored in client configs.
  64. ### 3. Configure Your MCP Client
  65. #### Connecting via Streamable HTTP (Mode B — Recommended for Shared or Container Setups)
  66. - **Antigravity / Antigravity IDE** ([MCP setup docs](https://antigravity.google/docs/mcp)):
  67. Use `serverUrl` (required for Streamable HTTP in current Antigravity releases; do not use `httpUrl`):
  68. ```json
  69. {
  70. "mcpServers": {
  71. "google-ads-mcp": {
  72. "serverUrl": "http://localhost:8080/mcp"
  73. }
  74. }
  75. }
  76. ```
  77. - **Codex CLI** ([Codex MCP docs](https://developers.openai.com/codex/mcp/)):
  78. ```shell
  79. codex mcp add google_ads --url http://localhost:8080/mcp
  80. codex mcp login google_ads
  81. ```
  82. #### Spawning Locally via `stdio` + ADC (Mode A)
  83. Add the following `mcpServers` block to your client configuration, replacing `PATH_TO_CREDENTIALS_JSON` and `YOUR_PROJECT_ID` ([how to find your project ID](https://support.google.com/googleapi/answer/7014113)):
  84. ```json
  85. {
  86. "mcpServers": {
  87. "google-ads-mcp": {
  88. "command": "pipx",
  89. "args": [
  90. "run",
  91. "--spec",
  92. "git+https://github.com/googleads/google-ads-mcp.git",
  93. "google-ads-mcp"
  94. ],
  95. "env": {
  96. "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
  97. "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
  98. }
  99. }
  100. }
  101. }
  102. ```
  103. > **Tip:** To pin a published PyPI release instead of tracking `main`, change `"git+https://github.com/googleads/google-ads-mcp.git"` to `"google-ads-mcp==X.Y.Z"`. Note that `stdio` mode stores the ADC file path in the client's config; prefer [Local Container Deployment](#local-container-deployment-docker--podman) if client configs are shared or synced across tools.
  104. #### Manager Accounts (`login_customer_id`)
  105. If you access client accounts through a Google Ads Manager Account (MCC), you can either:
  106. 1. Pass `login_customer_id` per tool call (takes precedence when provided), or
  107. 2. Set `GOOGLE_ADS_LOGIN_CUSTOMER_ID` in the server's `env` configuration as a default:
  108. ```json
  109. "env": {
  110. "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
  111. "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID",
  112. "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
  113. }
  114. ```
  115. See [Google Ads API Call Structure (`login-customer-id`)](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) for details.
  116. #### Other MCP Clients (Claude Code, Cursor, VS Code)
  117. The `mcpServers` JSON format works across standard MCP clients—place it in the client's configuration file (for example, `~/.claude/settings.json` for Claude Code, `.cursor/mcp.json` for Cursor, or `.vscode/mcp.json` for VS Code).
  118. ---
  119. ## Tools & Resources
  120. ### Available Tools
  121. By default, tools are mounted with their category namespace prefix (`<namespace>_<tool>`). Namespaces and individual tools can be customized via `tools_config.yaml` (see [Configuring and Namespacing Tools](#configuring-and-namespacing-tools)).
  122. | Default Tool Name | Namespace | Type | Description |
  123. | :--- | :--- | :--- | :--- |
  124. | `search_search` | `search` | Read | Queries Google Ads account data using GAQL (Google Ads Query Language). |
  125. | `metadata_get_resource_metadata` | `metadata` | Read | Retrieves selectable, filterable, and sortable field metadata for a Google Ads API resource (e.g., `campaign`). |
  126. | `customers_list_accessible_customers` | `customers` | Read | Lists customer IDs directly accessible to the authenticated user. |
  127. | `assets_create_asset` | `assets` | Mutate | Creates Google Ads assets (`TEXT`, `IMAGE`, `YOUTUBE_VIDEO`, `SITELINK`, `CALLOUT`, `STRUCTURED_SNIPPET`, plus additional types via `extra_params`). Note: `image_asset_path` is local `stdio` only; use base64 `image_asset_data` over HTTP. |
  128. | `assets_upload_video_asset` | `assets` | Mutate | Uploads a local video file to YouTube via a background task so it can be referenced by video assets (local `stdio` mode only). |
  129. | `labels_manage_labels` | `labels` | Mutate | Creates, updates, and removes account labels. |
  130. | `labels_manage_label_associations` | `labels` | Mutate | Creates and removes label associations on `CAMPAIGN`, `CUSTOMER`, `AD_GROUP`, and `AD_GROUP_CRITERION` resources. |
  131. ### Available Resources
  132. | Resource URI | Description |
  133. | :--- | :--- |
  134. | `resource://discovery-document` | Google Ads API REST discovery document describing the API surface, resources, methods, and schemas. (Prefer `metadata_get_resource_metadata` when looking up specific queryable GAQL fields.) |
  135. | `resource://metrics` | Reference documentation for reporting metrics in the Google Ads API. |
  136. | `resource://segments` | Reference documentation for reporting segments in the Google Ads API. |
  137. | `resource://release-notes` | Release notes for the latest version of the Google Ads API. |
  138. ---
  139. ## Configuration & Security
  140. ### Propose & Confirm Safety Workflow
  141. All mutate tools (`assets_create_asset`, `assets_upload_video_asset`, `labels_manage_labels`, and `labels_manage_label_associations`) enforce a mandatory two-step safety workflow:
  142. 1. **Propose (`validate_only=True`, default)**: Validates the operation (including a Google Ads API `validate_only` dry run where supported) without committing changes. Returns human-readable `change_items` and a cryptographic `checksum` bound to the `customer_id` and parameters.
  143. 2. **Confirm (`validate_only=False`)**: After explicit user approval, pass the exact same parameters and `customer_id` along with the `checksum` from step 1. Missing or mismatched checksums are rejected before mutating the account.
  144. ### Configuring and Namespacing Tools
  145. Use `tools_config.yaml` to selectively enable or disable tool categories/tools and customize namespace prefixes. A default configuration with all categories enabled is bundled with the package.
  146. The server resolves `tools_config.yaml` in the following order:
  147. 1. Path specified by `GOOGLE_ADS_MCP_TOOLS_CONFIG`.
  148. 2. `./tools_config.yaml` in the current working directory.
  149. 3. The default `tools_config.yaml` bundled with the package.
  150. If an explicitly configured file is missing or any resolved file is invalid, startup fails immediately.
  151. ```yaml
  152. namespaces:
  153. # Enable category with default prefix -> "customers_list_accessible_customers"
  154. customers: true
  155. # Enable category with custom prefix -> "query_search"
  156. search: "query"
  157. # Fine-grained control over individual tools in a category
  158. metadata:
  159. enabled: true
  160. prefix: "metadata"
  161. enabled_tools:
  162. - get_resource_metadata: true
  163. # Disable mutate categories for a strictly read-only deployment
  164. labels: false
  165. assets: false
  166. ```
  167. ### Tool Call Auditability
  168. Every tool invocation—including background worker runs via `TasksExtension`—is recorded by `AuditMiddleware`, which emits structured JSON events (`"tool_call"` and `"task_execution"`) to the `ads_mcp.audit` logger:
  169. - **Actor (`actor`)**: Authentication mode (`oauth` or `adc`), opaque OAuth identifiers (`sub`, `client_id`, `scopes`), MCP `session_id` (per-request on sessionless MCP `2026-07-28` connections), and MCP `client_info`. Raw PII such as `email` and `name` is omitted.
  170. - **Execution context**: Unique `audit_id`, tool name, MCP `call_id` (and `task_id` for background tasks), `received_at` UTC timestamp, `customer_id`, `login_customer_id`, `mutation_phase` (`READ`, `PROPOSE`, or `COMMIT`), `checksum`, `schema_hash`, `status` (`completed`, `empty`, `enqueued`, `error`, or `failed`), and `duration_ms`.
  171. - **Redacted arguments**: `arguments` with binary/base64 media payloads and Google Ads sensitive/PII fields (in both `snake_case` and protobuf JSON `camelCase`) replaced with `REDACTED`.
  172. Audit records can also be persisted to `filetree`, `redis`, `firestore`, or `memory` via the `GOOGLE_ADS_MCP_AUDIT_STORAGE_*` variables below. Stored records remain unencrypted redacted JSON by default so backends like Firestore stay queryable across OAuth secret rotations; set `GOOGLE_ADS_MCP_AUDIT_STORAGE_ENCRYPTION_KEY` to enable Fernet encryption with a dedicated HKDF salt isolated from OAuth token storage.
  173. ### Environment Variables Reference
  174. #### Core & OAuth Proxy
  175. | Variable | Description |
  176. | :--- | :--- |
  177. | `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | Optional default Manager Account (MCC) customer ID when accessing client accounts through a manager. |
  178. | `GOOGLE_ADS_MCP_TOOLS_CONFIG` | Optional path to a custom `tools_config.yaml` file. |
  179. | `PORT` | HTTP listen port when running in Streamable HTTP mode (default: `8080`). |
  180. | `GOOGLE_ADS_MCP_OAUTH_CLIENT_ID` | Google Cloud OAuth 2.0 Client ID. Setting both ID and Secret enables OAuth Proxy & Streamable HTTP mode. |
  181. | `GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET` | Google Cloud OAuth 2.0 Client Secret. |
  182. | `GOOGLE_ADS_MCP_BASE_URL` | Public base URL of the HTTP server (default: `http://localhost:8080`). |
  183. | `GOOGLE_ADS_MCP_JWT_SIGNING_KEY` | Recommended for multi-instance or persistent HTTP deployments to sign FastMCP JWTs consistently. |
  184. #### OAuth State & Audit Persistence
  185. Both OAuth state storage (`GOOGLE_ADS_MCP_STORAGE_*`) and optional audit record storage (`GOOGLE_ADS_MCP_AUDIT_STORAGE_*`) support `filetree`, `redis`, `firestore`, and `memory` backends.
  186. > **Optional backend extras:** Install `pip install "py-key-value-aio[redis]"` for Redis or `pip install "google-ads-mcp[firestore]"` for Firestore.
  187. | OAuth Storage Variable | Audit Storage Equivalent | Description |
  188. | :--- | :--- | :--- |
  189. | `GOOGLE_ADS_MCP_STORAGE_TYPE` | `GOOGLE_ADS_MCP_AUDIT_STORAGE_TYPE` | Backend type: `filetree`, `redis`, `firestore`, or `memory`. |
  190. | `GOOGLE_ADS_MCP_STORAGE_PATH` | `GOOGLE_ADS_MCP_AUDIT_STORAGE_PATH` | Directory path when using the `filetree` backend. |
  191. | `GOOGLE_ADS_MCP_STORAGE_REDIS_URL` | `GOOGLE_ADS_MCP_AUDIT_STORAGE_REDIS_URL` | Redis connection URL (defaults to `redis://localhost:6379/0`). |
  192. | `GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT` | `GOOGLE_ADS_MCP_AUDIT_STORAGE_FIRESTORE_PROJECT` | GCP project for `firestore` (defaults to ADC project; setting this implicitly selects `firestore`). |
  193. | `GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE` | `GOOGLE_ADS_MCP_AUDIT_STORAGE_FIRESTORE_DATABASE` | Firestore database name (defaults to `(default)`). |
  194. | `GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY` | `GOOGLE_ADS_MCP_AUDIT_STORAGE_ENCRYPTION_KEY` | Fernet key (or secret material) for encrypting stored records. OAuth storage falls back to JWT/OAuth secret; audit storage is unencrypted unless explicitly set. |
  195. | `GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION` | `GOOGLE_ADS_MCP_AUDIT_STORAGE_DISABLE_ENCRYPTION` | Set to `true` to disable storage encryption. |
  196. | — | `GOOGLE_ADS_MCP_AUDIT_STORAGE_TTL_SECONDS` | Optional retention TTL (in positive seconds) for persisted audit records. |
  197. ---
  198. ## Deployment
  199. Remote and containerized deployments run in Streamable HTTP mode using the FastMCP OAuth Proxy (`GOOGLE_ADS_MCP_OAUTH_CLIENT_ID` and `GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET`).
  200. ### Local Container Deployment (Docker / Podman)
  201. Running the server in a local rootless container isolates OAuth secrets and storage encryption keys from MCP client configurations.
  202. 1. **Build the image:**
  203. ```shell
  204. docker build --tag google-ads-mcp:latest .
  205. # or with Podman:
  206. podman build --tag localhost/google-ads-mcp:latest --file Dockerfile .
  207. ```
  208. 2. **Run with isolated secrets and persistent OAuth state:**
  209. Keep your `.env` file outside the repository with owner-only permissions, bind port `8080` strictly to `127.0.0.1` for local agents, and mount a dedicated volume for `filetree` OAuth state (`GOOGLE_ADS_MCP_STORAGE_PATH=/var/lib/google-ads-mcp`):
  210. ```shell
  211. docker run -d --name google-ads-mcp \
  212. -p 127.0.0.1:8080:8080 \
  213. --env-file /absolute/host/path/google-ads-mcp.env \
  214. -v google-ads-mcp-oauth:/var/lib/google-ads-mcp:rw \
  215. --read-only --security-opt no-new-privileges --cap-drop ALL \
  216. google-ads-mcp:latest
  217. ```
  218. For systemd/Podman Quadlet setups, the equivalent `.container` unit is:
  219. ```ini
  220. [Container]
  221. Image=localhost/google-ads-mcp:latest
  222. PublishPort=127.0.0.1:8080:8080
  223. EnvironmentFile=/absolute/host/path/google-ads-mcp.env
  224. Volume=google-ads-mcp-oauth.volume:/var/lib/google-ads-mcp:rw
  225. ReadOnly=true
  226. NoNewPrivileges=true
  227. DropCapability=all
  228. ```
  229. #### HTTP Interoperability Notes
  230. - **Stateful Streamable HTTP**: Keep stateful Streamable HTTP enabled (the default). It serves both MCP 2025 clients (`Mcp-Session-Id` + `GET` SSE) and MCP 2026 clients (sessionless `POST` + `subscriptions/listen`). Do not enable FastMCP's `stateless_http` option on a shared endpoint, as it removes the legacy `GET` SSE channel.
  231. - **FastMCP 4 & OAuth callback compatibility**: The server targets `fastmcp>=4.0.6,<5` and `mcp[cli]>=2.0.0,<3`. The `Dockerfile` applies a version-guarded patch that stops advertising RFC 9207 `authorization_response_iss_parameter_supported` as mandatory for compatibility with Codex CLI OAuth callbacks, failing the build loudly if the upstream FastMCP target changes.
  232. ### Google Cloud Run Deployment
  233. #### Prerequisites
  234. 1. A Google Cloud project with billing enabled.
  235. 2. The `gcloud` CLI authenticated and configured:
  236. ```shell
  237. gcloud config set project YOUR_PROJECT_ID
  238. ```
  239. #### Step 1: Build and Push the Container Image
  240. Create an Artifact Registry repository and build with Cloud Build (no local Docker required):
  241. ```shell
  242. gcloud artifacts repositories create mcp-servers \
  243. --repository-format=docker \
  244. --location=us-central1
  245. gcloud builds submit \
  246. --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
  247. ```
  248. > **Using Firestore for persistent OAuth/audit storage on Cloud Run:**
  249. > 1. Install the Firestore extra in your `Dockerfile` (`RUN uv pip install --system ".[firestore]"`).
  250. > 2. Provision a Firestore database in your GCP project and grant the Cloud Run service account `roles/datastore.user`.
  251. > 3. Note that `py-key-value-aio`'s Firestore store filters expired entries on read without deleting them (and writes `expires_at` as a string rather than a native timestamp), so plan a periodic cleanup job for long-running deployments—or use Redis (`GOOGLE_ADS_MCP_STORAGE_TYPE=redis`), which expires keys natively.
  252. #### Step 2: Deploy to Cloud Run
  253. Deploy the service with your OAuth credentials, persistent JWT signing key, and storage backend. On first deploy, you can omit `GOOGLE_ADS_MCP_BASE_URL` until Cloud Run assigns your service URL, then update it:
  254. ```shell
  255. gcloud run deploy google-ads-mcp \
  256. --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  257. --platform managed \
  258. --region us-central1 \
  259. --allow-unauthenticated \
  260. --set-env-vars="GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=YOUR_JWT_SIGNING_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore"
  261. ```
  262. Add `GOOGLE_ADS_LOGIN_CUSTOMER_ID=YOUR_MANAGER_CUSTOMER_ID` to `--set-env-vars` if your accounts are accessed via a manager account.
  263. #### Step 3: Connect Your MCP Client
  264. Point your MCP client at the Cloud Run `/mcp` endpoint:
  265. ```json
  266. {
  267. "mcpServers": {
  268. "google-ads-mcp": {
  269. "serverUrl": "https://your-cloud-run-url.a.run.app/mcp"
  270. }
  271. }
  272. }
  273. ```
  274. ---
  275. ## Try It Out
  276. Launch your MCP client and verify that `google-ads-mcp` appears in the connected servers list. Try prompts such as:
  277. - `What can the google-ads-mcp server do?`
  278. - `What customers do I have access to?`
  279. - `How many active campaigns do I have for customer ID 1234567890?`
  280. - `How is my campaign performance this week for customer ID 1234567890?`
  281. > **Tip:** Most tools require a `customer_id`. Including the customer ID directly in your prompt makes switching across multiple accounts faster.
  282. ---
  283. ## Contributing
  284. Contributions are welcome! See the [Contributing Guide](CONTRIBUTING.md) to get started.
  285. Project maintainers can find the Trusted Publishing and release workflow in the [Release Guide](docs/releasing.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.