Which integrations are available for this server?

Provides tools for querying and managing Google Ads accounts, campaigns, keywords, assets, and performance metrics via the Google Ads API.

How do I use mcp-gads?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-gads show me my active campaigns" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-gads

by pijusz

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Quick Start

1. Get Credentials

You need a Google Ads API developer token and OAuth client credentials.

Download your OAuth client JSON from Google Cloud Console
Set environment variables:

export GOOGLE_ADS_DEVELOPER_TOKEN=your-token
export GOOGLE_ADS_CREDENTIALS_PATH=./credentials.json

Run the setup helper to authorize:

npx mcp-gads setup

This opens your browser, completes OAuth, and saves a refresh token.

2. Add to Claude Code

claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- npx -y mcp-gads@latest

That's it. Restart Claude Code and the tools are available. Every session runs the latest version automatically.

Also works with bunx mcp-gads@latest if you have Bun. Requires Node 22+ when running via npx.

If your environment blocks npm registry access at runtime, install once and run the published binary name directly:

npm i -g mcp-gads@latest
claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- mcp-gads

Download a pre-built binary from Releases:

Platform	File
macOS (Apple Silicon)	`mcp-gads-darwin-arm64`
macOS (Intel)	`mcp-gads-darwin-x64`
Linux	`mcp-gads-linux-x64`
Windows	`mcp-gads-windows-x64.exe`

macOS / Linux:

curl -Lo mcp-gads https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-darwin-arm64
chmod +x mcp-gads
sudo mv mcp-gads /usr/local/bin/
claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- /usr/local/bin/mcp-gads

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\mcp-gads.exe"
claude mcp add google-ads --scope user --transport stdio -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token -e GOOGLE_ADS_CREDENTIALS_PATH=C:\path\to\credentials.json -- "%LOCALAPPDATA%\mcp-gads.exe"

ChatGPT Codex

Codex uses TOML, not JSON. Install once, then add to ~/.codex/config.toml:

npm i -g mcp-gads

[mcp_servers.gads]
command = "mcp-gads"

[mcp_servers.gads.env]
GOOGLE_ADS_DEVELOPER_TOKEN = "your-token"
GOOGLE_ADS_CREDENTIALS_PATH = "/absolute/path/to/credentials.json"

Three gotchas that cause silent failures on Codex:

Don't use npx -y without raising the timeout. Codex's default startup_timeout_sec is 10s, which is too short for npx's first-run download. A global install (above) or the prebuilt binary sidesteps this entirely. If you must use npx, add startup_timeout_sec = 30.
Env vars must go under [mcp_servers.gads.env]. Codex does not inherit the parent shell environment into stdio servers — exporting vars in your shell won't reach the server.
Use absolute paths for GOOGLE_ADS_CREDENTIALS_PATH. Codex spawns the server with its own cwd, so relative paths silently miss.

On Windows some Codex versions use startup_timeout_ms = 20000 instead of _sec.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "mcp-gads@latest"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-ads": {
      "command": "/usr/local/bin/mcp-gads",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-ads": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\mcp-gads.exe",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "C:\\path\\to\\credentials.json"
      }
    }
  }
}

Related MCP server: google-ads-mcp

Tools (39)

Account Management

Tool	Description
`list_accounts`	List all accessible Google Ads accounts
`get_account_currency`	Get the currency code for an account
`get_account_hierarchy`	Get MCC account tree (manager -> client)

Queries

Tool	Description
`execute_gaql_query`	Run any GAQL query (table output)
`run_gaql`	Run GAQL with format options (table/json/csv)
`get_gaql_help`	GAQL reference guide with syntax, resources, and examples
`list_resources`	List valid GAQL FROM clause resources

Campaigns

Tool	Description
`get_campaign_performance`	Campaign metrics (impressions, clicks, cost, conversions)
`get_budget_utilization`	Budget amounts vs actual spend

Tool	Description
`get_ad_performance`	Ad-level performance metrics
`get_ad_creatives`	RSA headlines, descriptions, final URLs

Assets

Tool	Description
`get_image_assets`	List image assets with URLs and dimensions
`download_image_asset`	Download a specific image asset to disk
`get_asset_usage`	Find where assets are used (campaigns, ad groups)
`analyze_image_assets`	Image asset performance with metrics

Keywords

Tool	Description
`generate_keyword_ideas`	Keyword Planner suggestions from seed keywords
`get_keyword_volumes`	Historical search volume for specific keywords
`get_quality_scores`	Quality scores with component breakdown
`get_search_terms`	Actual search queries triggering your ads
`get_paid_organic_search_terms`	Paid vs organic clicks per query (needs Search Console link)
`get_search_term_insights`	Search demand categories — the only view into Performance Max & Demand Gen queries

Geographic & Device

Tool	Description
`get_geographic_performance`	Performance by location
`get_device_performance`	Performance by device type

Insights

Tool	Description
`get_recommendations`	Google's AI optimization suggestions
`get_change_history`	Recent account changes

Extended Reporting

Tool	Description
`get_ad_group_performance`	Ad group metrics with optional campaign filter
`get_conversion_actions`	Conversion actions with settings and performance
`get_account_summary`	Quick dashboard: totals + top 5 campaigns
`get_impression_share`	Competitive position: impression share and lost IS
`get_ad_schedule_performance`	Performance by hour or day of week
`get_audience_performance`	Demographics: age range and gender breakdowns
`get_landing_page_performance`	Landing page URLs with metrics
`get_placement_performance`	Display/PMax placement details
`get_asset_group_performance`	PMax asset group metrics and ad strength
`get_video_performance`	YouTube/video view rates and quartile completion
`get_labels`	Labels and their campaign/ad group assignments

Write Tools (disabled by default)

Enable with GOOGLE_ADS_ENABLE_MUTATIONS=true:

Tool	Description
`update_campaign_status`	Pause/enable a campaign
`update_ad_group_status`	Pause/enable an ad group
`update_ad_status`	Pause/enable an ad
`update_campaign_budget`	Change daily budget amount
`add_negative_keywords`	Add negative keywords to a campaign

Configuration

Variable	Required	Default	Description
`GOOGLE_ADS_DEVELOPER_TOKEN`	Yes	—	API developer token
`GOOGLE_ADS_CREDENTIALS_PATH`	Yes	—	Path to OAuth client JSON
`GOOGLE_ADS_AUTH_TYPE`	No	`oauth`	`oauth` or `service_account`
`GOOGLE_ADS_CUSTOMER_ID`	No	—	Default customer ID (skips passing it per tool)
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	No	—	MCC manager account ID
`GOOGLE_ADS_IMPERSONATION_EMAIL`	No	—	Service account impersonation email
`GOOGLE_ADS_ENABLE_MUTATIONS`	No	`false`	Enable write tools
`GOOGLE_ADS_ENV_FILE`	No	`.env`	Path to .env file (loaded if present, never overrides existing env)
`GOOGLE_ADS_API_VERSION`	No	`v25`	Google Ads API version

Updates

Using npx @latest (recommended): You always get the latest version — no manual updates needed.

Using a binary: The server checks for new releases on startup and logs to stderr if outdated:

[mcp-gads] v0.2.0 available (current: v0.1.0). Download: https://github.com/pijusz/mcp-gads/releases/latest

Check your installed version:

mcp-gads --version

To update, download the new binary and replace the old one.

Development

Requires Bun.

git clone https://github.com/pijusz/mcp-gads.git
cd mcp-gads
bun install
bun test           # tests
bun run build      # standalone binary
bun run inspect    # MCP Inspector
bun run check      # biome format + lint

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

google-ads
ai.adramp
Google Ads MCP server — manage campaigns, keywords, and metrics.
Marketing E-commerce & Retail
2
Google Ads MCP by MarkifactOAuth
com.markifact
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Marketing App Automation Finance
11
Google AdsOAuth
ai.b77
Read and manage your Google Ads account in chat.
Marketing
1
AdTAO MCPOAuth
io.adtao
Google Ads MCP with 20,000+ account peer context and staged approve-then-execute writes.
Marketing App Automation
1

Related MCP Servers

Google Ads MCP Server
Marketing Search
MaxGhenis
A
license
A
quality
F
maintenance
A read-write MCP server for managing Google Ads campaigns, ad groups, keywords, and ads via natural language.
Updated 8 months ago (2026-02-10 11:16 UTC)
12
2
-
google-ads-mcpofficial
Marketing Search
googleads
A
license
B
quality
A
maintenance
MCP server that provides tools and resources for interacting with Google Ads API, enabling search, metadata retrieval, and account management through natural language.
Updated 8 days ago (2026-10-09 14:00 UTC)
3
3,046 PyPI
1,041
Apache 2.0
google-ads-mcp-server
Marketing E-commerce & Retail
getmcpads-com
A
license
A
quality
A
maintenance
Enables reading and analyzing Google Ads data, planning keywords, and previewing campaign changes before applying them, all through natural language.
Updated a month ago (2026-09-20 11:27 UTC)
35
95 npm
Apache 2.0
Google Ads MCP Server
Marketing
PradeepGontupuli
A
license
A
quality
B
maintenance
Enables LLMs and AI agents to query and explore Google Ads accounts and API resources through MCP tools and resources, including account information, resource metadata, metrics, segments, and release notes.
Updated a month ago (2026-09-11 10:27 UTC)
3
Apache 2.0