How do I use mcp-gads?

1. Click on "Install 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 Related Servers Score Discussions

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 18+ 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 Server

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

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 Tools (disabled by default)

Enable with GOOGLE_ADS_ENABLE_EXTENDED_TOOLS=true:

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_ENABLE_EXTENDED_TOOLS`	No	`false`	Enable extended read tools (11 extra)
`GOOGLE_ADS_ENV_FILE`	No	`.env`	Path to .env file (loaded if present, never overrides existing env)
`GOOGLE_ADS_API_VERSION`	No	`v23`	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 installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

6wRelease cycle

2Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pijusz/mcp-gads'

If you have feedback or need assistance with the MCP directory API, please join our Discord server