Mcp Gads

io.github.pijusz由 GitHub 账号 pijusz 发布v0.5.4更新于 Oct 24, 2026

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

已验证STDIO仅桌面数据与分析商业与电商

概览

AI 生成的概览

一个本地 MCP 服务器，让助手用自然语言查询 Google Ads 账户、广告系列、关键词、素材和效果指标。

可以做什么
列出账户、币种和 MCC 层级，并运行任意 GAQL 查询，支持表格、JSON 或 CSV 输出，附带 GAQL 帮助和资源列表。读取广告系列、广告组、广告、预算、转化、展示份额、时段、受众、落地页、展示位置、素材组、视频和标签报告。查看关键词建议、搜索量、质量得分、搜索词和搜索词洞察。检查图片素材、下载到磁盘并查看素材使用位置。获取 Google 优化建议和账户更改历史。启用写入工具后，可暂停或启用广告系列、广告组和广告，修改每日预算并添加否定关键词。
适用场景
适合让助手提取并解释 Google Ads 效果数据、研究关键词、审查搜索词或素材，或在不打开 Google Ads 界面的情况下做小幅账户调整。
运行要求
通过 npx（需 Node 22+）、bunx、全局 npm 安装或 macOS、Linux、Windows 预编译二进制以 stdio 在本地运行。需要 GOOGLE_ADS_DEVELOPER_TOKEN 中的 Google Ads API 开发者令牌，以及 GOOGLE_ADS_CREDENTIALS_PATH 指向的 OAuth 客户端 JSON；setup 命令会完成 OAuth 并保存刷新令牌。可选变量用于设置认证类型、默认客户 ID、MCC 登录 ID、模拟邮箱、API 版本和启用写入。
安装前请注意
需要 Google Ads API 凭据和 OAuth 刷新令牌，可访问你的广告账户；请妥善保管凭据文件和令牌。写入工具默认关闭，但一旦 GOOGLE_ADS_ENABLE_MUTATIONS 为 true，助手可暂停或启用广告系列、广告组和广告、修改每日预算并添加否定关键词，会影响实际花费。下载图片素材会写入磁盘文件。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Gads，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 79040e3

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.5.4最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分