Skip to main content
Glama
Google Ads MCP Server

Google Ads MCP Server

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

Related MCP server: Google Ads MCP Server

Installation

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

Available Tools

11 tools
create_conversion_actionC

Create a new Conversion Action (e.g., for website, phone calls)

Inputs: name (required), type (required), category (required), value.

create_responsive_display_adC

Create a Responsive Display Ad with Ad Controls (e.g., enable video creation)

Inputs: ad_group_id (required), headlines (required), descriptions (required), enable_video_creation.

enable_campaignC

Enable/resume a paused campaign

Inputs: campaign_id (required).

export_reportC

Export campaign data to CSV or JSON format

Inputs: format (required), days.

get_campaign_detailsC

Get detailed information about a specific campaign

Inputs: campaign_id (required), days.

get_campaignsC

Fetch Google Ads campaign performance data

Inputs: days, status.

get_conversion_actionsB

List all Conversion Actions for the account

Inputs: no named parameters.

get_performance_summaryC

Get overall account performance summary

Inputs: days.

get_top_performersC

Get top performing campaigns by specified metric

Inputs: metric, limit, days.

pause_campaignC

Pause a specific campaign

Inputs: campaign_id (required).

update_campaign_budgetC

Update the daily budget for a campaign

Inputs: campaign_id (required), budget_euros (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific resources like campaigns, conversion actions, ads, and reports, with clear separation between actions like enable_campaign and pause_campaign. However, get_campaigns and get_campaign_details could potentially be confused as both retrieve campaign data, though their descriptions differentiate them as performance data vs. detailed information.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, such as create_conversion_action, get_campaigns, and update_campaign_budget. This uniformity makes the tool set predictable and easy to understand at a glance.

    Tool Count5/5

    With 11 tools, the server is well-scoped for Google Ads management, covering key operations like campaign control, reporting, and ad creation. This count is reasonable and aligns with the domain's complexity without being overwhelming or insufficient.

    Completeness4/5

    The tool set provides strong coverage for core Google Ads workflows, including campaign lifecycle (create, enable, pause, update budget), reporting (export, performance summary), and ad management. A minor gap is the lack of tools for deleting resources or managing ad groups, but agents can likely work around this with the available operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables comprehensive Google Ads campaign management and analytics through the Google Ads API. Supports querying campaigns, ad groups, keywords, performance metrics, and executing custom GAQL queries with token-efficient implementation.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables comprehensive Google Ads campaign management and analysis through natural language, including performance metrics, keyword optimization, budget management, and custom GAQL queries.
      100
      17
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables comprehensive management of Google Ads campaigns through natural language, including campaign creation, ad group management, keyword operations, Performance Max campaigns, conversion tracking, and performance insights with support for multiple accounts.
      3
      -