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