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:

export GOOGLE_ADS_DEVELOPER_TOKEN=your-token

export GOOGLE_ADS_CREDENTIALS_PATH=./credentials.json

1. 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

Alternative: standalone binary

Download a pre-built binary from Releases:

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:

Using npx (auto-updates)

{

"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)

{

"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)

{

"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

Queries

Campaigns

Ads

Assets

Keywords

Geographic & Device

Insights

Extended Reporting

Write Tools (disabled by default)

Enable with GOOGLE_ADS_ENABLE_MUTATIONS=true:

Configuration

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