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 分