Skip to content
Back to search

google-ads-mcp

Google Ads MCP server: read tools with service-account auth, plus opt-in campaign building

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/walma-labs--google-ads-mcp"><img src="/api/listings/walma-labs--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.

1. Developer token

Every Google Ads API call needs a developer token. It comes from **Tools → API Center** in a Google Ads **manager** account. A new token starts at test access, which only works against test accounts; apply for **Basic access** to read real accounts. Approval can take a few days.

2. Service account and key

1. In [Google Cloud Console](https://console.cloud.google.com/), pick or create a project. 2. Enable the **Google Ads API**. 3. IAM & Admin → Service accounts → Create. No project roles are needed. 4. Keys → Add key → JSON. Save the file outside any repository, for example `~/.config/gcloud/google-ads-service-account.json`.

3. Give the service account access in Google Ads

In the Google Ads account (or in a manager account above it), open **Admin → Access and security → Users** and add the service account's email address (`…@….iam.gserviceaccount.com`). **Read only** is enough for the read tools; writing needs **Standard**.

The server sees exactly the accounts the service account was added to. Use one service account per organisation: an account added for two customers shows both to everyone who can reach the server.

If the service account was added to a manager account rather than to the ad accounts themselves, set `GOOGLE_ADS_LOGIN_CUSTOMER_ID` to the manager's customer id.

4. Add it to your MCP client

**Claude Code:**

claude mcp add google-ads --scope user \
  -e GOOGLE_ADS_SERVICE_ACCOUNT_FILE=~/.config/gcloud/google-ads-service-account.json \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token \
  -- npx -y github:Walma-Labs/google-ads-mcp

**Claude Desktop, Cursor and others** (`mcpServers` in the client's config):

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "github:Walma-Labs/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_SERVICE_ACCOUNT_FILE": "~/.config/gcloud/google-ads-service-account.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token"
      }
    }
  }
}

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 · 144 lines
  1. # google-ads-mcp — Google Ads MCP server
  2. A [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude, Cursor, Claude Code and any other MCP client access to Google Ads: campaigns, ad groups, keywords, search terms, budgets, conversions and anything else the Google Ads Query Language (GAQL) can select. It is read-only by default and can be allowed to build and edit campaigns.
  3. It is a TypeScript port of the read tools in Google's own [google-ads-mcp](https://github.com/googleads/google-ads-mcp), with the same tool names and arguments, so prompts written for one work on the other. What differs:
  4. - **Read-only unless you switch writing on.** Out of the box the server only has tools that search and list. Writing is one extra tool that exists only when `GOOGLE_ADS_WRITE_TOOLS` is set, with rules about what it may do (see [Writing](#writing)).
  5. - **Service-account auth, no gcloud.** Point it at a key file, or pass the key inline.
  6. - **Streamable HTTP as well as stdio.** It can run centrally. This is how [Walma](https://walma.ai) serves it to whole organisations through its AI gateway.
  7. - **Three runtime dependencies.** It calls the REST API directly instead of using the gRPC client library.
  8. Built and used by [Walma AI](https://walma.ai).
  9. ## Tools
  10. | Tool | What it does |
  11. |---|---|
  12. | `list_accessible_customers` | The customer ids the service account can reach directly |
  13. | `get_resource_metadata` | The selectable, filterable and sortable fields of a resource, with its compatible metrics and segments |
  14. | `search` | A GAQL query built from `fields`, `resource`, `conditions`, `orderings` and `limit` |
  15. Rows come back as one object per row, keyed by the field names that were selected:
  16. ```json
  17. { "campaign.name": "Brand", "metrics.clicks": "120", "metrics.cost_micros": "45000000" }
  18. ```
  19. Cost and bid fields ending in `_micros` are millionths of the account currency. A call returns at most 10 000 rows and says `"truncated": true` when there were more.
  20. ## Writing
  21. Set `GOOGLE_ADS_WRITE_TOOLS` and the server gains a fourth tool, `mutate`, which sends a batch of [mutate operations](https://developers.google.com/google-ads/api/rest/reference/rest/latest/customers.googleAds/mutate) that succeed together or not at all. The service account then needs **Standard** access in Google Ads instead of read-only.
  22. | Value | The tool may |
  23. |---|---|
  24. | unset | nothing: the tool is not registered |
  25. | `draft` (or `1`) | create and edit campaigns, budgets, asset groups, assets, ad groups, ads, criteria and labels. Everything new is paused, and it cannot enable a campaign or change an existing budget |
  26. | `live` | all of that, and enable campaigns and change budgets |
  27. Whatever the value:
  28. - **A dry run comes first.** `validate_only` defaults to `true`: Google Ads checks the request and nothing changes. Applying takes a second call with `validate_only: false`.
  29. - **A new campaign must be created `PAUSED`.** Someone turns it on, in Google Ads or (at `live`) by asking for it.
  30. - **Campaigns, budgets, ad groups and asset groups cannot be removed.** That cannot be undone in Google Ads; pause them instead.
  31. - **Only campaign building blocks.** Users, billing, account budgets, conversion settings and links to other products are refused.
  32. These rules are checked in the server before anything is sent, so they hold whatever the model is asked to do. They are not a spending limit: at `draft` an edit to a campaign that is already running (its ads, keywords, bidding targets) takes effect at once. Have your MCP client ask before each `mutate` call.
  33. Every caller writes as the same service account, so Google Ads' change history shows the service account, not the person.
  34. Image and video assets have to exist in the account already, or be sent as base64 in an `assetOperation`. The server does not fetch files from URLs.
  35. ## Setup
  36. ### 1. Developer token
  37. Every Google Ads API call needs a developer token. It comes from **Tools → API Center** in a Google Ads **manager** account. A new token starts at test access, which only works against test accounts; apply for **Basic access** to read real accounts. Approval can take a few days.
  38. ### 2. Service account and key
  39. 1. In [Google Cloud Console](https://console.cloud.google.com/), pick or create a project.
  40. 2. Enable the **Google Ads API**.
  41. 3. IAM & Admin → Service accounts → Create. No project roles are needed.
  42. 4. Keys → Add key → JSON. Save the file outside any repository, for example `~/.config/gcloud/google-ads-service-account.json`.
  43. ### 3. Give the service account access in Google Ads
  44. In the Google Ads account (or in a manager account above it), open **Admin → Access and security → Users** and add the service account's email address (`…@….iam.gserviceaccount.com`). **Read only** is enough for the read tools; writing needs **Standard**.
  45. The server sees exactly the accounts the service account was added to. Use one service account per organisation: an account added for two customers shows both to everyone who can reach the server.
  46. If the service account was added to a manager account rather than to the ad accounts themselves, set `GOOGLE_ADS_LOGIN_CUSTOMER_ID` to the manager's customer id.
  47. ### 4. Add it to your MCP client
  48. **Claude Code:**
  49. ```sh
  50. claude mcp add google-ads --scope user \
  51. -e GOOGLE_ADS_SERVICE_ACCOUNT_FILE=~/.config/gcloud/google-ads-service-account.json \
  52. -e GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token \
  53. -- npx -y github:Walma-Labs/google-ads-mcp
  54. ```
  55. **Claude Desktop, Cursor and others** (`mcpServers` in the client's config):
  56. ```json
  57. {
  58. "mcpServers": {
  59. "google-ads": {
  60. "command": "npx",
  61. "args": ["-y", "github:Walma-Labs/google-ads-mcp"],
  62. "env": {
  63. "GOOGLE_ADS_SERVICE_ACCOUNT_FILE": "~/.config/gcloud/google-ads-service-account.json",
  64. "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token"
  65. }
  66. }
  67. }
  68. }
  69. ```
  70. ## Configuration
  71. | Variable | |
  72. |---|---|
  73. | `GOOGLE_ADS_SERVICE_ACCOUNT_FILE` | Path to the service-account key file |
  74. | `GOOGLE_ADS_SERVICE_ACCOUNT_JSON` | The key as inline JSON. Wins over the file when both are set |
  75. | `GOOGLE_ADS_DEVELOPER_TOKEN` | Required |
  76. | `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | Optional manager account. A tool call can also pass `login_customer_id` |
  77. | `GOOGLE_ADS_WRITE_TOOLS` | Optional: `draft` or `live`. See [Writing](#writing) |
  78. | `GOOGLE_ADS_API_VERSION` | Optional, default `v25`. Google retires a version about a year after its release |
  79. ## Running over HTTP
  80. ```sh
  81. npm run build
  82. PORT=8080 npm run start:http
  83. ```
  84. `POST /` is the MCP endpoint (streamable HTTP, stateless) and `GET /healthz` answers `ok`. There is **no authentication** in this process: put it behind something that authenticates callers.
  85. ## Using it as a library
  86. ```ts
  87. import { createGoogleAdsClient, createGoogleAdsServer } from "@walma-labs/google-ads-mcp";
  88. const client = createGoogleAdsClient(); // built once; caches its access token
  89. const server = createGoogleAdsServer(client); // a fresh McpServer per request
  90. ```
  91. ## Development
  92. ```sh
  93. npm install
  94. npm test
  95. ```
  96. The tests drive the real MCP wire against a mocked request function, so they need neither network nor credentials.
  97. When `GOOGLE_ADS_API_VERSION` moves on, refresh `src/resources.ts` from Google's `ads_mcp/gaql_resources.txt`.
  98. ## Licence
  99. Apache-2.0. Tool names, argument contracts, tool descriptions and the resource list derive from Google's google-ads-mcp; see `NOTICE`.

Ratings and comments

Sign in to rate this skill.

Sign in

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