Mcp Gads

io.github.pijuszPublished by GitHub account pijuszv0.5.4Updated Oct 24, 2026

Google Ads MCP server — query campaigns, keywords, assets & more via natural language

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

A local MCP server that lets an assistant query Google Ads accounts, campaigns, keywords, assets and performance metrics in natural language.

What you can do
List accounts, currencies and MCC hierarchies, and run arbitrary GAQL queries with table, JSON or CSV output plus GAQL help and resource lists. Read campaign, ad group, ad, budget, conversion, impression share, schedule, audience, landing page, placement, asset group, video and label reporting. Review keyword ideas, search volumes, quality scores, search terms and search term insights. Inspect image assets, download them to disk and see where assets are used. Fetch Google recommendations and account change history. Optionally pause or enable campaigns, ad groups and ads, change daily budgets and add negative keywords when write tools are enabled.
When to use it
Useful when you want an assistant to pull and explain Google Ads performance data, research keywords, audit search terms or assets, or make small account changes without opening the Google Ads interface.
Requirements
Runs locally over stdio via npx (Node 22+), bunx, a global npm install or a prebuilt binary for macOS, Linux or Windows. Needs a Google Ads API developer token in GOOGLE_ADS_DEVELOPER_TOKEN and an OAuth client JSON path in GOOGLE_ADS_CREDENTIALS_PATH; a setup command completes OAuth and saves a refresh token. Optional variables set auth type, default customer ID, MCC login ID, impersonation email, API version and mutation enabling.
Before you install
Requires Google Ads API credentials and an OAuth refresh token, which grant access to your ad accounts; keep the credentials file and token private. Write tools are off by default but, once GOOGLE_ADS_ENABLE_MUTATIONS is true, the assistant can pause or enable campaigns, ad groups and ads, change daily budgets and add negative keywords, which affects live spending. Downloading image assets writes files to disk.

Installation

In SourceWeft

  1. Open Mcp Gads in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[mcp-gads]

Google Ads MCP server — query campaigns, keywords, assets & more via natural language.
Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client.

Quick Start

1. Get Credentials

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

  1. Download your OAuth client JSON from Google Cloud Console
  2. Set environment variables:
bash
export GOOGLE_ADS_DEVELOPER_TOKEN=your-tokenexport GOOGLE_ADS_CREDENTIALS_PATH=./credentials.json
  1. Run the setup helper to authorize:
bash
npx mcp-gads setup

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

2. Add to Claude Code

bash
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:

bash
npm i -g mcp-gads@latestclaude 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
Alternative: standalone binary

Download a pre-built binary from Releases:

PlatformFile
macOS (Apple Silicon)mcp-gads-darwin-arm64
macOS (Intel)mcp-gads-darwin-x64
Linuxmcp-gads-linux-x64
Windowsmcp-gads-windows-x64.exe

macOS / Linux:

bash
curl -Lo mcp-gads https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-darwin-arm64chmod +x mcp-gadssudo 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):

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:

bash
npm i -g mcp-gads
toml
[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:

Using npx (auto-updates)
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"      }    }  }}
Using binary (macOS / Linux)
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"      }    }  }}
Using binary (Windows)
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"      }    }  }}

Tools (39)

Account Management

ToolDescription
list_accountsList all accessible Google Ads accounts
get_account_currencyGet the currency code for an account
get_account_hierarchyGet MCC account tree (manager -> client)

Queries

ToolDescription
execute_gaql_queryRun any GAQL query (table output)
run_gaqlRun GAQL with format options (table/json/csv)
get_gaql_helpGAQL reference guide with syntax, resources, and examples
list_resourcesList valid GAQL FROM clause resources

Campaigns

ToolDescription
get_campaign_performanceCampaign metrics (impressions, clicks, cost, conversions)
get_budget_utilizationBudget amounts vs actual spend

Ads

ToolDescription
get_ad_performanceAd-level performance metrics
get_ad_creativesRSA headlines, descriptions, final URLs

Assets

ToolDescription
get_image_assetsList image assets with URLs and dimensions
download_image_assetDownload a specific image asset to disk
get_asset_usageFind where assets are used (campaigns, ad groups)
analyze_image_assetsImage asset performance with metrics

Keywords

ToolDescription
generate_keyword_ideasKeyword Planner suggestions from seed keywords
get_keyword_volumesHistorical search volume for specific keywords
get_quality_scoresQuality scores with component breakdown
get_search_termsActual search queries triggering your ads
get_paid_organic_search_termsPaid vs organic clicks per query (needs Search Console link)
get_search_term_insightsSearch demand categories — the only view into Performance Max & Demand Gen queries

Geographic & Device

ToolDescription
get_geographic_performancePerformance by location
get_device_performancePerformance by device type

Insights

ToolDescription
get_recommendationsGoogle's AI optimization suggestions
get_change_historyRecent account changes

Extended Reporting

ToolDescription
get_ad_group_performanceAd group metrics with optional campaign filter
get_conversion_actionsConversion actions with settings and performance
get_account_summaryQuick dashboard: totals + top 5 campaigns
get_impression_shareCompetitive position: impression share and lost IS
get_ad_schedule_performancePerformance by hour or day of week
get_audience_performanceDemographics: age range and gender breakdowns
get_landing_page_performanceLanding page URLs with metrics
get_placement_performanceDisplay/PMax placement details
get_asset_group_performancePMax asset group metrics and ad strength
get_video_performanceYouTube/video view rates and quartile completion
get_labelsLabels and their campaign/ad group assignments

Write Tools (disabled by default)

Enable with GOOGLE_ADS_ENABLE_MUTATIONS=true:

ToolDescription
update_campaign_statusPause/enable a campaign
update_ad_group_statusPause/enable an ad group
update_ad_statusPause/enable an ad
update_campaign_budgetChange daily budget amount
add_negative_keywordsAdd negative keywords to a campaign

Configuration

VariableRequiredDefaultDescription
GOOGLE_ADS_DEVELOPER_TOKENYes—API developer token
GOOGLE_ADS_CREDENTIALS_PATHYes—Path to OAuth client JSON
GOOGLE_ADS_AUTH_TYPENooauthoauth or service_account
GOOGLE_ADS_CUSTOMER_IDNo—Default customer ID (skips passing it per tool)
GOOGLE_ADS_LOGIN_CUSTOMER_IDNo—MCC manager account ID
GOOGLE_ADS_IMPERSONATION_EMAILNo—Service account impersonation email
GOOGLE_ADS_ENABLE_MUTATIONSNofalseEnable write tools
GOOGLE_ADS_ENV_FILENo.envPath to .env file (loaded if present, never overrides existing env)
GOOGLE_ADS_API_VERSIONNov26Google 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:

bash
mcp-gads --version

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

Development

Requires Bun.

bash
git clone https://github.com/pijusz/mcp-gads.gitcd mcp-gadsbun installbun test           # testsbun run build      # standalone binarybun run inspect    # MCP Inspectorbun run check      # biome format + lint

License

MIT

Source: README.md at commit 79040e3

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.4LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts