@bossforce.ai/mcp-google-ads

MCP server for the Google Ads API (REST, v24). Read Google Ads data with GAQL (Google Ads Query Language): discover accessible accounts, list campaigns and run arbitrary read queries for reporting and performance analysis.

Gated. This integration only works once you have an approved Google Ads API developer token. A token is requested in the API Center of a Google Ads manager (MCC) account and must be reviewed and approved by Google. Until then a token can only call test accounts.

Credentials

| Env | Secret | How to obtain | | ------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------- | | GOOGLE_ADS_CLIENT_ID | yes | OAuth2 client id (Google Cloud Console). Provided by the platform as client_id. | | GOOGLE_ADS_CLIENT_SECRET | yes | OAuth2 client secret. Provided by the platform as client_secret. | | GOOGLE_ADS_REFRESH_TOKEN | yes | Obtained automatically when you authorize Google access (scope https://www.googleapis.com/auth/adwords). | | GOOGLE_ADS_DEVELOPER_TOKEN | yes | Your approved developer token from the API Center of a Google Ads manager account. | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | no | The manager (MCC) account customer id, digits only with no dashes — sent as the login-customer-id header. |

Credentials are read lazily, so the server boots and answers tools/list without them; calls fail with an auth error until they are set.

Auth

The server exchanges the refresh token for a short-lived access token at https://oauth2.googleapis.com/token (grant_type=refresh_token) and caches it, re-fetching once on a 401. Every API call carries three headers the API requires: authorization: Bearer <token>, developer-token and login-customer-id (the manager id with dashes stripped).

Tools

| Tool | Arguments | Returns | | --------------------------- | ------------------------------------- | ------------------------------------------------ | | search | customer_id, query, page_token? | GAQL results array (and nextPageToken) | | list_campaigns | customer_id, page_token? | campaigns with id, name, status, channel, budget | | list_accessible_customers | — | resourceNames of accessible customer accounts |

search runs any GAQL statement against POST /customers/{customerId}/googleAds:search. customer_id is digits only (dashes are stripped automatically). Use list_accessible_customers to discover the ids to pass.

Develop

pnpm --filter @bossforce.ai/mcp-google-ads build
pnpm --filter @bossforce.ai/mcp-google-ads test

Regenerate the tools/list snapshot after an intentional signature change:

UPDATE_SNAPSHOTS=1 pnpm --filter @bossforce.ai/mcp-google-ads test