tb-gads-mcp

Google Ads MCP server — exposes Google Ads API capabilities as Model Context Protocol tools for Claude, Gemini CLI, and other MCP-compatible AI clients.

Combines the rich feature set of google-marketing-solutions/google_ads_mcp with the official structure of googleads/google-ads-mcp, rebuilt as a TypeScript npm package.

Tools

| Tool | Description | |------|-------------| | list_accessible_customers | Lists Google Ads customer IDs accessible by the authenticated user | | execute_gaql | Executes a raw GAQL query and returns results | | search | Structured search — builds GAQL from fields, resource, conditions, orderings, limit; includes full field reference in tool description | | get_gaql_doc | Returns the GAQL language reference guide (Markdown) | | get_reporting_view_doc | Returns field listing for a specific resource, or overview of all resources | | get_reporting_fields_doc | Returns selectable/filterable/sortable metadata for specific fields |

Resources (MCP)

| URI | Description | |-----|-------------| | gaql://guide | GAQL language reference (Markdown) | | gaql://views | Overview of all Google Ads API reporting resources |

Setup

1. Get a developer token

Get your Google Ads API developer token from Google Ads Manager Accounts.

2. Configure authentication

Two auth methods are supported (pick one):

Option A — Service account / Application Default Credentials (recommended)

This matches the auth approach of the official googleads/google-ads-mcp.

1. Create a service account in Google Cloud Console
2. Grant it access to your Google Ads account(s) as a user with the required role
3. Download the JSON key file
4. Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Or use gcloud auth application-default login for local dev without a key file.

Option B — OAuth2 user credentials

1. Create an OAuth2 client in Google Cloud Console with scope https://www.googleapis.com/auth/adwords
2. Exchange for a refresh token via Google's OAuth2 Playground
3. Set GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, and GOOGLE_ADS_REFRESH_TOKEN

3. Configure environment

Copy .env.example to .env:

# Service account (Option A)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token

# Or OAuth2 (Option B)
# GOOGLE_ADS_CLIENT_ID=your_client_id
# GOOGLE_ADS_CLIENT_SECRET=your_client_secret
# GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token
# GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token

# Optional
# GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890

Usage

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@unboundai/[email protected]"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_developer_token",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "optional_mcc_id"
      }
    }
  }
}

OAuth2 alternative:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@unboundai/[email protected]"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_developer_token"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@unboundai/[email protected]"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_developer_token"
      }
    }
  }
}

Direct run

# Install globally
npm install -g @unboundai/tb-gads-mcp
tb-gads-mcp

# Or run without installing
npx @unboundai/[email protected]

Development

# Install dependencies
npm install

# Run in development (ts-node)
npm run dev

# Build
npm run build

# Type-check only
npm run typecheck

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_ADS_DEVELOPER_TOKEN | Yes | Google Ads API developer token | | GOOGLE_APPLICATION_CREDENTIALS | One of A or B | Path to service account JSON key file | | GOOGLE_ADS_CLIENT_ID | One of A or B | OAuth2 client ID | | GOOGLE_ADS_CLIENT_SECRET | One of A or B | OAuth2 client secret | | GOOGLE_ADS_REFRESH_TOKEN | One of A or B | OAuth2 refresh token (adwords scope) | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | No | Default MCC manager account ID | | GOOGLE_ADS_API_VERSION | No | API version (default: v23) |

Example queries

Once connected to Claude or another MCP client, you can ask natural language questions:

• "List all my accessible Google Ads accounts"
• "Show campaign performance for account 1234567890 over the last 30 days"
• "What search terms drove the most conversions last month?"
• "Get the Quality Score for all active keywords in my campaigns"
• "Show me the GAQL reference for how to filter by date"

License

Apache-2.0