Google Ads MCP Server

Google Ads MCP Server

A Model Context Protocol (MCP) server that provides access to Google Ads API for comprehensive campaign analytics. Use with Claude Code for conversational ad performance analysis.

Features

• Google OAuth Authentication: Secure login with Google for multi-user access
• Remote HTTP Access: StreamableHTTP transport for remote MCP connections
• 11 Analytics Tools: Comprehensive Google Ads performance analytics
• Account information
• Campaign, Ad Group, and Ad performance metrics
• Keyword performance with quality scores
• Search term reports
• Performance Max asset group analysis
• Conversion action tracking
• Demographic performance (age, gender, device)
• Budget pacing and utilization analysis
• Multi-level data export
• Docker Support: Containerized deployment with health checks
• Production Ready: Environment-based configuration, security best practices

Prerequisites

• Node.js 24+ (or Docker)
• Google Ads API access (apply for developer token)
• Google Cloud project with OAuth 2.0 credentials
• Google Ads account with active campaigns

Quick Setup (Local Development)

1. Clone and Install

git clone https://github.com/jgdeutsch/google-ads-mcp.git
cd google-ads-mcp
npm install

2. Get Google Ads API Credentials

1. Create a Google Cloud project at console.cloud.google.com
2. Enable the Google Ads API
3. Create OAuth 2.0 credentials (Desktop application type)
4. Get your developer token from Google Ads API Center

3. Get Refresh Token

# Edit scripts/get_refresh_token.py with your CLIENT_ID and CLIENT_SECRET
python3 scripts/get_refresh_token.py

4. Configure Environment

cp .env.example .env

# Edit .env and add:
# - GOOGLE_ADS_CLIENT_ID (from OAuth credentials)
# - GOOGLE_ADS_CLIENT_SECRET (from OAuth credentials)
# - GOOGLE_ADS_REFRESH_TOKEN (from step 3)
# - GOOGLE_ADS_DEVELOPER_TOKEN (from API Center)
# - GOOGLE_ADS_LOGIN_CUSTOMER_ID (MCC account, no dashes)
# - GOOGLE_ADS_CUSTOMER_ID (ad account, no dashes)
# - SESSION_SECRET (generate with: openssl rand -base64 32)
# - REQUIRE_AUTH=false (for local use)

5. Start the Server

npm run build && npm start
# Or for development with hot reload:
npm run dev

6. Configure Claude Code

Add to ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "google-ads": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

7. Test in Claude Code

You: "Show me campaign performance for last 7 days"
You: "What are my top performing keywords?"
You: "Show search terms with highest spend"
You: "How's my budget pacing this month?"

Available Tools

| # | Tool | Description | |---|------|-------------| | 1 | get-account | Account info (name, currency, timezone, status) | | 2 | get-campaign-performance | Campaign metrics with budget and bidding strategy | | 3 | get-ad-group-performance | Ad group metrics with campaign context | | 4 | get-ad-performance | Individual ad performance metrics | | 5 | get-keyword-performance | Keyword metrics with quality scores | | 6 | get-search-terms | Search queries that triggered your ads | | 7 | get-asset-group-performance | Performance Max asset group metrics | | 8 | get-conversions | Conversion actions and conversion metrics | | 9 | get-demographic-performance | Performance by age, gender, or device | | 10 | get-budget-analysis | Budget pacing and utilization rates | | 11 | export-data | Multi-level data export with daily breakdowns |

Date Ranges

All tools support these date range presets:

• TODAY, YESTERDAY
• LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS
• THIS_MONTH, LAST_MONTH

Docker Deployment

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Production Deployment (Railway)

1. Fork this repo
2. Connect to Railway
3. Set environment variables in Railway dashboard
4. Deploy (uses Dockerfile automatically)

Environment Variables

See .env.example for full documentation.

Required

| Variable | Description | |----------|-------------| | GOOGLE_ADS_CLIENT_ID | OAuth client ID | | GOOGLE_ADS_CLIENT_SECRET | OAuth client secret | | GOOGLE_ADS_REFRESH_TOKEN | OAuth refresh token | | GOOGLE_ADS_DEVELOPER_TOKEN | Google Ads API developer token | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | MCC account ID (no dashes) | | GOOGLE_ADS_CUSTOMER_ID | Ad account ID (no dashes) | | SESSION_SECRET | Random 32+ char secret |

Optional

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | Server port | | HOST | 0.0.0.0 | Bind address | | NODE_ENV | development | Environment | | REQUIRE_AUTH | false | Enable OAuth for team access | | SESSION_TTL | 86400000 | Session duration (ms) |

Development

npm install          # Install dependencies
npm run type-check   # Type checking
npm run dev          # Development with hot reload
npm run build        # Build TypeScript
npm start            # Run built version

Security

• OAuth 2.0 with PKCE for authentication
• Bearer tokens with 24-hour expiry
• Non-root Docker container
• No secrets in version control
• .env excluded via .gitignore

License

MIT

Support

• GitHub Issues: https://github.com/jgdeutsch/google-ads-mcp/issues

---

Built with the Model Context Protocol SDK