MCP Server for Google Ads

TypeScript implementation of an MCP server for Google Ads API with GCloud/ADC authentication. Provides tools for campaign management, performance reporting, and account operations with Multi-Customer Center (MCC) support.

Table of Contents

• Prerequisites

• Quick Start

• Authentication

• Environment Variables

• Multi-Tenant Mode

• Client-Specific Instructions

  • Claude Desktop

  • Claude Code

  • Cursor

  • VS Code

  • Local Installation

• Available Tools

  • 1. manage_auth

  • 2. list_resources

  • 3. execute_gaql_query

  • 4. get_performance

  • 5. gaql_help

• Development

• License

Prerequisites

• Node.js 18+ and npm

• A GCP project with the Google Ads API enabled

• Ensure the credentials you use (user/ADC) have the Service Usage Consumer role on that project (grants serviceusage.services.use)

• A Google Ads Developer Token is required:

  • Documentation

  • Application form

Quick Start

Using npx (Recommended)

Authentication

The server uses Google Application Default Credentials (ADC) for secure authentication. This is the recommended approach as it provides automatic token refresh and secure credential management.

How Authentication Works

1. Application Default Credentials (ADC): The server first attempts to use ADC, which automatically finds credentials in this order:

   • Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to a credential file

   • User credentials from gcloud auth application-default login

   • Service account attached to the compute resource (GCE, Cloud Functions, etc.)

2. CLI Token Fallback: If enabled with GOOGLE_ADS_GCLOUD_USE_CLI=true, the server can fall back to using gcloud auth print-access-token for authentication

3. Automatic Token Refresh: Both methods handle token refresh automatically

Setting Up Authentication

Method 1: ADC via gcloud (Recommended)

Method 2: Existing ADC File

Place your ADC file at .auth/adc.json in the project directory, or set GOOGLE_APPLICATION_CREDENTIALS to point to your authorized_user JSON file.

Method 3: OAuth Device Flow

Use manage_auth { "action": "oauth_login" } with GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET environment variables to create an ADC file interactively.

Environment Variables

Required

• GOOGLE_ADS_DEVELOPER_TOKEN: Your Google Ads API developer token (required for all API calls)

Optional

• GOOGLE_ADS_ACCOUNT_ID (optional): Default Google Ads account ID (10-digit customer ID without dashes). Used as the default customer for all operations when not specified explicitly.

• GOOGLE_ADS_MANAGER_ACCOUNT_ID (optional): For Multi-Customer Center (MCC) accounts - the manager account ID that acts as the login customer. Required when accessing accounts under an MCC. This is typically your MCC account ID (10-digit numeric ID, no dashes). Note: you can override this per call using the login_customer_id (aka MCC/manager account id) parameter in tools like execute_gaql_query and get_performance.

• GOOGLE_APPLICATION_CREDENTIALS (optional): Path to an ADC credentials file (authorized_user JSON). Takes precedence over default ADC locations.

• GOOGLE_ADS_QUOTA_PROJECT_ID (optional): GCP project ID used for quota/billing. Helps avoid 403 errors due to missing quota. Typically your active gcloud project ID.

• GOOGLE_ADS_API_VERSION (optional): API version string (e.g., v20, v21, v22). Defaults to v21 if unset. Supports format normalization ("21" → "v21").

• GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET (optional): Desktop OAuth client credentials used by manage_auth with action: "oauth_login" to create local ADC. Only needed if you cannot use gcloud.

• GOOGLE_ADS_ACCESS_TOKEN (optional): Used by unit tests; for mocked tests this can be any non-empty string. When set, bypasses ADC. For real API calls prefer ADC; if used, this must be a real OAuth 2.0 access token with the Google Ads scope and will not auto-refresh.

Example Configuration

Client-Specific Instructions

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\\Claude\\claude_desktop_config.json (Windows):

Claude Code

Install and configure with a single command:

For more details, see the Claude Code MCP documentation.

Cursor

Add to your MCP settings in Cursor. Go to Cursor Settings > Features > Model Context Protocol:

For detailed setup instructions, see the Cursor MCP documentation.

VS Code

Install the MCP extension and add the server configuration:

1. Install the "MCP Manager" extension from the marketplace

2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

3. Run "MCP: Add Server"

4. Configure the server:

For more information, see the VS Code MCP documentation.

Local Installation

For local development or when you want to run from source:

1. Clone and Build

2. Configure Your MCP Client

3. Development Mode

For development with auto-reload:

Multi-Tenant Mode

Multi-tenant mode allows hosted deployments to accept Google Ads credentials at connection time (no filesystem storage) and keep them immutable for the session lifecycle.

Enable via environment:

• ENABLE_RUNTIME_CREDENTIALS=true (default: false)

• RUNTIME_CREDENTIAL_TTL Session TTL in seconds (default: 3600)

• MAX_CONNECTIONS Maximum in-memory sessions (default: 1000)

• CONNECTION_SWEEP_INTERVAL Cleanup interval in seconds (default: 300)

• VERIFY_TOKEN_SCOPE Optional. When true, validates Ads scope at session establishment

• ALLOWED_CUSTOMER_IDS Optional allowlist of customer IDs (comma-separated)

• GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET Optional, for refresh flows

• HTTPS_PROXY Optional proxy for outbound requests

• NODE_TLS_REJECT_UNAUTHORIZED For proxy/cert handling when required

• STRICT_IMMUTABLE_AUTH Optional. When true, blocks re-setting credentials for an existing session (default allows overwrite with a warning)

• OBSERVABILITY_ENABLED Optional. Set to false to disable structured JSON logs (default enabled). Alternatively set OBSERVABILITY=off.

Behavioral differences when enabled:

• Credentials must be provided via set_session_credentials

• No fallback to ADC/env credentials

• manage_auth is disabled

• Each tool call must include session_key

• Developer token is required in provided credentials

• Sticky sessions required for multi-process deployments

Session tools:

1. set_session_credentials

   • Request:

• Response: { "status": "success", "session_key": "...", "expires_in": 3600 }

2. get_credential_status

   • Request: { "session_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }

   • Response: { "has_credentials": true, "expires_in": 3542, "has_refresh_token": true, "masked_token": "ya29****abcd" }

3. end_session

   • Request: { "session_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }

   • Response: { "status": "session_ended" }

Using standard tools in multi-tenant mode: include session_key in inputs. Example:

Client usage examples

• Establish session, then execute a GAQL query and get performance with session_key:

4. refresh_access_token

When a refresh_token is provided and OAuth client env is set, this tool refreshes the access token for the session.

Request

Response (success)

Response (invalid grant)

Observability

The server emits structured JSON events to stderr (12-factor style) for application-side collection. Each event includes:

Control via env:

• OBSERVABILITY_ENABLED=false (disable)

• OBSERVABILITY=off (disable)

Error Payloads

All tools return structured error payloads when failures occur:

Common codes include: ERR_INPUT, ERR_NOT_ENABLED, ERR_IMMUTABLE_AUTH, ERR_INVALID_GRANT, ERR_INSUFFICIENT_SCOPE, and HTTP_<status> for API responses.

Live Multi-Tenant Integration Test (optional)

You can run a live multi-tenant test flow using environment-provided credentials. Recommended gating:

• Set VITEST_REAL=1 and ENABLE_RUNTIME_CREDENTIALS=true

• Provide runtime test credentials via env (examples):

  • TEST_ACCESS_TOKEN, TEST_REFRESH_TOKEN, TEST_DEVELOPER_TOKEN

  • TEST_LOGIN_CUSTOMER_ID, TEST_QUOTA_PROJECT_ID

• Steps:

  1. Call set_session_credentials with test env values

  2. Run execute_gaql_query and get_performance with session_key

  3. Optionally call refresh_access_token to validate token refresh

  4. Optionally set VERIFY_TOKEN_SCOPE=true to validate scope against live API

  5. Optionally pass ALLOWED_CUSTOMER_IDS to validate allowlist enforcement

Keep the existing single-tenant live tests as primary validation; multi-tenant live tests are optional and depend on environment-provided credentials.

Per-Session Rate Limiting (Optional)

Token-bucket rate limiting protects quotas on a per-session basis when multi-tenant mode is enabled.

• Env (defaults in parentheses):

  • ENABLE_RATE_LIMITING (true)

  • REQUESTS_PER_SECOND (10)

  • RATE_LIMIT_BURST (20)

• Error payload on limit:

Rate limiting is enforced only in multi-tenant mode and only for session-bound tools.

Available Tools

1. manage_auth - Authentication management

Note: When ENABLE_RUNTIME_CREDENTIALS=true (multi-tenant mode), this tool is disabled and returns an error. Use the session tools instead.

Comprehensive authentication management tool with multiple actions:

action: 'status' (default)

• Environment inspection: Shows all Google Ads environment variables

• ADC file discovery: Locates and validates Application Default Credentials files

• Token validation: Checks access token presence and scopes via Google OAuth2 API

• Scope verification: Tests Google Ads API access by calling listAccessibleCustomers

• Account enumeration: Counts accessible customer accounts under current credentials

• Troubleshooting hints: Provides guidance when authentication issues are detected

action: 'oauth_login'

• Device OAuth flow: Interactive browser-based authentication using OAuth client credentials

• Requires env vars: GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET

• Saves ADC file: Creates authorized_user JSON at .auth/adc.json

• Scope validation: Automatically verifies Google Ads API access after completion

• Sets credentials: Updates GOOGLE_APPLICATION_CREDENTIALS for immediate use

action: 'switch'

• Configuration switching: Changes active gcloud configuration

• Requires: config_name parameter

• Auto-execution: Runs gcloud config configurations activate <name> when allow_subprocess=true

• Guidance: Provides next steps for refreshing ADC credentials with correct scopes

action: 'refresh'

• Credential refresh: Re-authenticates ADC with required Google Ads scopes

• Auto-execution: Runs gcloud auth application-default login with proper scopes

• Token verification: Prints access token to verify successful authentication

• Scope testing: Validates Google Ads API access after refresh

action: 'set_project'

• Project configuration: Sets default GCP project for gcloud

• Requires: project_id parameter

• Command: gcloud config set project <project_id>

action: 'set_quota_project'

• Quota project setup: Sets ADC quota project for billing attribution

• Requires: project_id parameter

• Command: gcloud auth application-default set-quota-project <project_id>

Safety Features

• Dry-run mode: Set allow_subprocess: false to see planned commands without execution

• gcloud detection: Automatically checks for gcloud CLI availability before execution

• Error handling: Provides clear error messages and installation links when gcloud is missing

• Timeout protection: Commands have built-in timeouts to prevent hanging

Example user prompts:

2. list_resources - List Google Ads resources

Lists various Google Ads resources with support for hierarchical relationships and multiple output formats.

Supported resource types:

• accounts - List accessible customer accounts

• campaigns - List campaigns

• ad_groups - List ad groups

• ads - List ads

• keywords - List keywords

• extensions - List ad extensions

Example user prompts:

3. execute_gaql_query - Execute Google Ads Query Language queries

Executes custom GAQL queries for advanced data retrieval and analysis with automatic pagination support.

Example user prompts:

4. get_performance - Get performance metrics

Retrieves performance metrics and reports for campaigns, ad groups, ads, and keywords with flexible filtering and segmentation.

Example user prompts:

5. gaql_help - Google Ads Query Language reference

Provides interactive help and documentation for Google Ads Query Language (GAQL), including available resources, fields, functions, and operators.

Example user prompts:

Development

Setup

Running Tests

Project Structure

License

MIT