mcp-gads

Google Ads MCP 服务——通过自然语言查询广告系列、关键字、素材等。
使用 Bun + TypeScript 构建。兼容 Claude、Cursor 和任何 MCP 客户端。

快速开始

1. 获取凭据

你需要一个 Google Ads API 开发者令牌和 OAuth 客户端凭据。

1. 从 Google Cloud Console下载 OAuth 客户端 JSON 文件
2. 设置环境变量：

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

3. 运行设置助手进行授权：

npx mcp-gads setup

这会打开浏览器，完成 OAuth 授权并保存刷新令牌。

2. 添加到 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

完成。重启 Claude Code 后即可使用这些工具。每次会话都会自动运行最新版本。

如果安装了 Bun，也可以使用 bunx mcp-gads@latest。 通过 npx 运行时需要 Node 22+。

如果你的环境会阻止运行时访问 npm registry，请先安装一次，然后直接运行已发布的二进制文件名称：

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

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

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 使用 TOML，而非 JSON。安装一次，然后添加到 ~/.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"

以下三点可能导致 Codex 静默失败：

• 使用 npx -y 时不要忘记延长超时时间。 Codex 的默认 startup_timeout_sec 为 10s，不足以完成 npx 首次运行时的下载。使用全局安装（如上所述）或预构建二进制文件即可完全避免此问题。如果必须使用 npx，请添加 startup_timeout_sec = 30。
• 环境变量必须放在 [mcp_servers.gads.env] 下。 Codex 不会将父 shell 环境继承到 stdio 服务中——在 shell 中导出变量不会传递给服务。
• GOOGLE_ADS_CREDENTIALS_PATH 必须使用绝对路径。 Codex 会使用自己的 cwd 启动服务，因此相对路径会静默失效。

在 Windows 上，部分 Codex 版本使用 startup_timeout_ms = 20000，而不是 _sec。

Claude Desktop

将以下内容添加到你的 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"
      }
    }
  }
}

工具（39）

账号管理

查询

广告系列

广告

素材

关键词

地理位置与设备

洞察

扩展报告

写入工具（默认禁用）

使用 GOOGLE_ADS_ENABLE_MUTATIONS=true 启用：

配置

更新

使用 npx @latest（推荐）：始终获取最新版本，无需手动更新。

使用二进制文件：服务会在启动时检查是否有新版本，并在版本过旧时将信息记录到 stderr：

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

检查已安装的版本：

mcp-gads --version

要更新，请下载新的二进制文件并替换旧文件。

开发

需要 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

许可证

MIT