google-ads-mcp-server

samihalawa/google-ads-mcp-server

3.2

If you are the rightful owner of google-ads-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for managing Google Ads campaigns programmatically, built with Node.js.

Tools
8
Resources
0
Prompts
0

Google Ads MCP Server (Node.js)

A Model Context Protocol (MCP) server for managing Google Ads campaigns programmatically, built with Node.js.

Features

Campaign Management

  • ✅ Fetch campaign performance data
  • ✅ Get detailed campaign information
  • ✅ Pause/enable campaigns
  • ✅ Update campaign budgets

Analytics & Reporting

  • ✅ Performance summaries
  • ✅ Top performer analysis
  • ✅ Export to CSV/JSON
  • ✅ Custom date ranges

Real-time Data

  • ✅ Live API integration
  • ✅ Up-to-date metrics
  • ✅ Conversion tracking
  • ✅ Budget monitoring

Installation

Global Installation (Recommended for CLI use)

npm install -g @samihalawa/google-ads-mcp-server

Local Installation (For project integration)

npm install @samihalawa/google-ads-mcp-server

Or with pnpm:

pnpm add @samihalawa/google-ads-mcp-server

Configuration

Simple .env Configuration (No YAML file needed!)

Create a .env file with your Google Ads API credentials as inline JSON:

# Google Ads API Configuration (JSON format - all in one line)
GOOGLE_ADS_CONFIG='{"client_id":"YOUR_CLIENT_ID.apps.googleusercontent.com","client_secret":"YOUR_CLIENT_SECRET","developer_token":"YOUR_DEVELOPER_TOKEN","refresh_token":"YOUR_REFRESH_TOKEN","login_customer_id":"YOUR_MANAGER_CUSTOMER_ID"}'

# Customer ID to query (without dashes)
GOOGLE_ADS_CUSTOMER_ID=1234567890

That's it! No separate YAML files needed. Everything is in your .env file.

Example Configuration

GOOGLE_ADS_CONFIG='{"client_id":"963208150325-mmhibhl91g39ma9jsvrgacpleraq4nfu.apps.googleusercontent.com","client_secret":"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","developer_token":"i525AeFTAacFOtQtWBjY6g","refresh_token":"1//04OmKZJ58yhQaCgYIARAAGAQSNwF-L9IrfyrhE7W2zk00iStBE8dCRazdeUgXiMVxH-WIr9PEh6W3_RvjRKSZx-FH3l3Dun5vWOc","login_customer_id":"4850172260"}'
GOOGLE_ADS_CUSTOMER_ID=1248495560

Usage

Running the Server

# Load .env and run
node server.js

Or with npx (no installation):

npx @samihalawa/google-ads-mcp-server

Using with MCP Clients

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["@samihalawa/google-ads-mcp-server"],
      "env": {
        "GOOGLE_ADS_CONFIG": "{\"client_id\":\"YOUR_CLIENT_ID\",\"client_secret\":\"YOUR_SECRET\",\"developer_token\":\"YOUR_TOKEN\",\"refresh_token\":\"YOUR_REFRESH\",\"login_customer_id\":\"YOUR_MANAGER_ID\"}",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Using with manus-mcp-cli

# Set environment variables
export GOOGLE_ADS_CONFIG='{"client_id":"...","client_secret":"...","developer_token":"...","refresh_token":"...","login_customer_id":"..."}'
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

# List available tools
manus-mcp-cli tool list --server google-ads

# Get campaigns
manus-mcp-cli tool call get_campaigns --server google-ads --input '{"days": 30}'

# Get performance summary
manus-mcp-cli tool call get_performance_summary --server google-ads --input '{"days": 7}'

# Pause a campaign
manus-mcp-cli tool call pause_campaign --server google-ads --input '{"campaign_id": "23207843655"}'

Available Tools

1. get_campaigns

Fetch all campaigns with performance metrics.

Parameters:

  • days (number, optional): Number of days to look back (default: 30)
  • status (string, optional): Filter by status - ENABLED, PAUSED, REMOVED, or ALL (default: ENABLED)

Example:

{
  "days": 30,
  "status": "ENABLED"
}

2. get_campaign_details

Get detailed information about a specific campaign.

Parameters:

  • campaign_id (string, required): The campaign ID
  • days (number, optional): Number of days to look back (default: 30)

Example:

{
  "campaign_id": "23207843655",
  "days": 30
}

3. get_performance_summary

Get overall account performance summary.

Parameters:

  • days (number, optional): Number of days to look back (default: 30)

Example:

{
  "days": 7
}

4. get_top_performers

Get top performing campaigns by specified metric.

Parameters:

  • metric (string, optional): Metric to rank by - ctr, conversions, cost, clicks, impressions (default: ctr)
  • limit (number, optional): Number of top campaigns to return (default: 5)
  • days (number, optional): Number of days to look back (default: 30)

Example:

{
  "metric": "ctr",
  "limit": 5,
  "days": 30
}

5. pause_campaign

Pause a specific campaign.

Parameters:

  • campaign_id (string, required): The campaign ID to pause

Example:

{
  "campaign_id": "23207843655"
}

6. enable_campaign

Enable/resume a paused campaign.

Parameters:

  • campaign_id (string, required): The campaign ID to enable

Example:

{
  "campaign_id": "23207843655"
}

7. update_campaign_budget

Update the daily budget for a campaign.

Parameters:

  • campaign_id (string, required): The campaign ID
  • budget_euros (number, required): New daily budget in euros

Example:

{
  "campaign_id": "23207843655",
  "budget_euros": 20.00
}

8. export_report

Export campaign data to CSV or JSON format.

Parameters:

  • format (string, required): Export format - csv or json
  • days (number, optional): Number of days to look back (default: 30)

Example:

{
  "format": "csv",
  "days": 30
}

Example Workflows

Daily Campaign Monitoring

# Get performance summary
manus-mcp-cli tool call get_performance_summary --server google-ads --input '{"days": 1}'

# Check top performers
manus-mcp-cli tool call get_top_performers --server google-ads --input '{"metric": "conversions", "limit": 3, "days": 7}'

Campaign Optimization

# Get campaign details
manus-mcp-cli tool call get_campaign_details --server google-ads --input '{"campaign_id": "23207843655", "days": 30}'

# Update budget if performing well
manus-mcp-cli tool call update_campaign_budget --server google-ads --input '{"campaign_id": "23207843655", "budget_euros": 25.00}'

# Pause if underperforming
manus-mcp-cli tool call pause_campaign --server google-ads --input '{"campaign_id": "23207843655"}'

Reporting

# Export to CSV
manus-mcp-cli tool call export_report --server google-ads --input '{"format": "csv", "days": 30}'

# Export to JSON
manus-mcp-cli tool call export_report --server google-ads --input '{"format": "json", "days": 7}'

Troubleshooting

"GOOGLE_ADS_CONFIG environment variable is required"

  • Make sure you've set the GOOGLE_ADS_CONFIG environment variable
  • Check that the JSON is valid and properly escaped
  • Ensure all required fields are present

"Failed to initialize Google Ads client"

  • Verify all credentials are correct
  • Ensure refresh token is still valid
  • Check that the JSON format is correct

"Campaign not found"

  • Verify the campaign ID is correct
  • Check that you have access to the campaign
  • Ensure the campaign hasn't been removed

"Unauthorized" errors

  • Refresh token may have expired - generate a new one
  • Check that the developer token is approved
  • Verify OAuth credentials are correct

API Rate Limits

Google Ads API has rate limits:

  • Basic access: 15,000 operations per day
  • Standard access: 40,000 operations per day

The MCP server automatically handles rate limiting and retries.

Security

  • Never commit .env to version control
  • Store credentials securely
  • Use environment variables for sensitive data
  • Rotate refresh tokens regularly
  • The .gitignore file already excludes .env files

Support

For issues or questions:

  1. Check the Google Ads API documentation
  2. Review the MCP specification
  3. Check server logs for error messages
  4. Open an issue on GitHub

License

MIT License - See LICENSE file for details

Version History

1.1.0 (2025-11-24)

  • Breaking Change: Switched from YAML to inline JSON configuration in .env
  • Removed js-yaml dependency
  • Simplified configuration - no separate files needed
  • Updated documentation

1.0.0 (2025-11-24)

  • Initial Node.js release
  • 8 core tools for campaign management
  • Real-time API integration
  • CSV/JSON export support
  • Complete documentation