Google Ads MCP Server
Model Context Protocol (MCP) server for Google Ads. The server acts as an OAuth 2.1 resource server: clients send a Clerk JWT (Authorization: Bearer). The server validates the token, then calls your mcp-ads-manager gateway with a shared secret to run Google Ads API requests with the user’s stored OAuth tokens.
Architecture
- Clerk issues JWTs for MCP clients. Configure
CLERK_AUDIENCEto the canonical MCP resource URL (same host/path asPUBLIC_BASE_URL+MCP_SERVER_PATH). - google-ads-mcp validates JWTs (JWKS) and exposes RFC 9728 metadata at
/.well-known/oauth-protected-resource(and the path-suffixed variant for streamable HTTP). - Gateway (
GATEWAY_BASE_URL) holds Google OAuth refresh tokens and proxies Google Ads API calls (e.g.googleAds:search,customers:listAccessibleCustomers) with the developer token. The MCP never forwards the Clerk token to Google.
Unauthenticated requests to the MCP path receive 401 with WWW-Authenticate: Bearer resource_metadata="...".
Required environment variables
| Variable | Purpose |
|---|---|
CLERK_JWKS_URL |
Clerk JWKS URL for JWT verification |
CLERK_ISSUER |
Expected JWT iss |
CLERK_AUDIENCE |
Expected JWT aud (MCP resource identifier) |
GATEWAY_BASE_URL |
Base URL of mcp-ads-manager (e.g. https://app.example.com) |
GATEWAY_INTERNAL_SECRET |
Must match gateway x-gateway-secret for internal routes |
Optional:
| Variable | Purpose |
|---|---|
PUBLIC_BASE_URL |
Public origin of this MCP (for metadata resource and resource_metadata URL). If unset, derived from the request. |
AUTHORIZATION_SERVER_URL |
OAuth authorization server for metadata (defaults to CLERK_ISSUER) |
MCP_REQUIRED_SCOPE |
If set, JWT must include this scope |
MCP_DEBUG_AUTH |
Set to true for verbose auth logs (per-request details, unverified JWT claim peek on failure) |
GATEWAY_CONNECT_URL / JUMON_CONNECT_URL |
URL shown when Google is not connected (defaults to {GATEWAY_BASE_URL}/connections) |
MCP_SERVER_HOST, PORT, MCP_SERVER_PATH |
HTTP bind and MCP path (defaults: 0.0.0.0, 8080, /mcp) |
Legacy aliases: JUMON_GATEWAY_BASE_URL, JUMON_GATEWAY_INTERNAL_SECRET for gateway URL and secret.
Cloud Run
Set PORT and listen on all interfaces. When Google sets K_SERVICE (always on Cloud Run), this server forces
MCP_SERVER_HOST to 0.0.0.0 so a mistaken 127.0.0.1 or localhost bind cannot break the platform health check. You must supply the same required variables as in the table above—especially CLERK_JWKS_URL, CLERK_ISSUER, GATEWAY_BASE_URL, and GATEWAY_INTERNAL_SECRET (often via Secrets). Set PUBLIC_BASE_URL to your service URL (for example https://--.run.app) so OAuth metadata is stable. JWKS is loaded on the first request that needs JWT validation, so startup is not blocked by an outbound fetch to Clerk.
Deploy the latest main from this repo (not only the total_count fix). Older revisions called Clerk JWKS before ListenAndServe, which could prevent the container from ever opening PORT during startup.
Run locally```bash
export CLERK_JWKS_URL="https://clerk.example.com/.well-known/jwks.json"
export CLERK_ISSUER="https://clerk.example.com"
export CLERK_AUDIENCE="https://your-mcp-host/mcp"
export GATEWAY_BASE_URL="http://localhost:3000"
export GATEWAY_INTERNAL_SECRET="your-gateway-secret"
export PUBLIC_BASE_URL="http://localhost:8080"
go run .
```
Smoke checks
- Metadata:
curl -s http://localhost:8080/.well-known/oauth-protected-resource | jq - Unauthorized MCP:
curl -i http://localhost:8080/mcp→ expect401andWWW-Authenticatewithresource_metadata - Authorized (real Clerk bearer token): call a tool via your MCP client with
Authorization: Bearer
MCP tools (account listing)
| Tool | Purpose |
|---|---|
list_ad_accounts |
Customers accessible to the connected Google user (ListAccessibleCustomers). No customer_id. |
list_client_accounts_under_manager |
GAQL customer_client rows under a manager (MCC)
customer_id (legacy hierarchy listing). |
Repository layout
internal/app/configs/— server, auth, gateway envinternal/infrastructure/security/— Clerk JWT verificationinternal/infrastructure/middleware/— bearer auth, logging, user id in contextinternal/infrastructure/api/gateway/— gateway HTTP client (connection check, proxy, refresh)internal/infrastructure/api/*/— GAQL + response mappinginternal/tools/listaccessiblecustomers/—list_ad_accountstoolinternal/tools/listadaccounts/—list_client_accounts_under_managertoolinternal/tools/*/— other MCP tools
