Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Google Ads MCP 伺服器：開發人員整合指南

Model Context Protocol (MCP) 是一項開放標準，可讓大型語言模型 (LLM) 與外部資料和應用程式安全互動。Google Ads MCP 伺服器提供 Google Ads API 的標準化橋接，讓 AI 代理能使用自然語言分析及擷取廣告活動資料。

社群資源和支援

GitHub 存放區：在 google-ads-mcp 存放區中查看示範和範例、回報錯誤或建議功能。

使用「Issues」分頁回報錯誤及提出功能要求。
社群：加入 Google Advertising Community Discord 的 #ads-api-ai-tools 頻道。

技術總覽

導入這個 MCP 伺服器後，您就不必編寫自訂「黏合程式碼」，用於 Google Ads API 驗證、資源擷取和資料剖析。伺服器會公開特定工具，LLM 可自行探索及叫用這些工具。

主要規格

通訊協定：MCP (Model Context Protocol)
模式： 唯讀 (目前版本)
語言：Python
傳輸：標準輸入內容/輸出 (stdio) 或可串流 HTTP (streamable-http / Cloud Run)
驗證：OAuth 2.0 或服務帳戶

互動迴圈的運作方式

要求：使用者提交查詢，例如「本週廣告活動成效如何？」。
探索：LLM 檢查可用工具，並找出 google-ads-mcp 搜尋功能。
執行：MCP 伺服器執行基礎 Python 邏輯，查詢 Google Ads API。
脈絡注入：結構化結果會傳回 LLM 的脈絡窗口。
回覆：LLM 將資料統整成人類可讀的答案。

開始使用

請按照下列步驟設定及使用 Google Ads MCP 伺服器。

必要條件

設定前，請確認您已從 Google Cloud 控制台取得下列憑證：

專案 ID：Google Cloud 專案 ID (GOOGLE_PROJECT_ID)。請查看 Google Ads API 總覽頁面，確認專案具備 Explorer 存取權、基本存取權或標準存取權。如果沒有，請申請其中一個存取層級。請注意，開發人員權杖 (GOOGLE_ADS_DEVELOPER_TOKEN) 已於 2026 年 9 月 9 日停用，且由於 API 存取層級與 Google Cloud 專案相關聯，因此最新版 Google Ads MCP 伺服器不再需要開發人員權杖。
OAuth 憑證：OAuth 2.0 用戶端 ID/用戶端密鑰組合，或一組應用程式預設憑證。

設定

如要將伺服器整合至與 MCP 相容的主機，請在主機的 MCP 設定檔 (例如 settings.json) 中新增下列項目，並將 GOOGLE_APPLICATION_CREDENTIALS 指向 ADC JSON 檔案 (或使用 gcloud auth application-default login 設定預設 ADC)。如果您透過管理員帳戶存取帳戶，也可以設定 GOOGLE_ADS_LOGIN_CUSTOMER_ID。請參閱代管商的說明文件，瞭解這項設定的確切位置和檔案名稱。

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

選用：為代理提供技能和 Developer Assistant

Google Ads MCP 伺服器可讓 AI 用戶端唯讀存取即時帳戶資料。為協助代理建構有效的 Google Ads 查詢語言 (GAQL) 查詢、診斷帳戶成效變化，以及產生用戶端程式庫程式碼，請將 MCP 伺服器與下列輔助工具搭配使用：

Google Ads API 代理程式技能：Google Ads API 專屬指令和工作流程的可攜式模組，包括 google-ads-api-mcp-setup、google-ads-api-account-diagnostics 和 google-ads-api-quickstart，可教導代理程式如何有效使用 Google Ads MCP 伺服器，並降低權杖負擔。使用單一指令安裝 (需要 Node.js)，或參閱 Google Ads API 代理程式技能指南，瞭解 Antigravity、Claude Code、Codex 和 Cursor 選項：
```
npx skills add google/skills/skills/ads
```
Google Ads API Developer Assistant：Google Antigravity 和 Claude Code 的模組化外掛程式，提供本機 Protobuf 結構定義檢查、程式輔助 GAQL 驗證、用戶端程式庫程式碼產生 (包括變動指令碼)，以及離線轉換疑難排解。如要瞭解運作方式，請參閱「什麼是 Google Ads API Developer Assistant？」一文，或按照安裝指南操作。

在 Google Cloud 部署

您也可以將這個 MCP 伺服器託管在 Google Cloud Run 或任何其他雲端式基礎架構，而非本機。如果您想在不同代理之間共用伺服器，或將伺服器做為網路服務執行，這項功能就非常實用。

必要條件

Google Cloud 專案。
已安裝 gcloud 指令列工具、完成驗證，並設定有效專案：
```
gcloud config set project YOUR_PROJECT_ID
```

建構及推送 Docker 映像檔

您可以使用 Cloud Build 建構映像檔並推送至 Artifact Registry，不必在本機安裝 Docker。

在 Artifact Registry 建立存放區：

gcloud artifacts repositories create mcp-servers \
  --repository-format=docker --location=us-central1

前往專案目錄：
```
cd <full path>/google-ads-mcp
```
建構並提交映像檔：
```
gcloud builds submit \
  --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
```
請注意，每當您想將已部署的伺服器更新至最新版本時，都必須執行這個步驟。

部署到 Google Cloud Run

請務必設定必要的環境變數：

GOOGLE_PROJECT_ID：您的 Google Cloud 專案 ID，具有適當的 API 存取層級。
GOOGLE_ADS_MCP_OAUTH_CLIENT_ID：OAuth 2.0 用戶端 ID (在 Google 雲端專案中設為網頁應用程式)，用於應用程式層級的 OAuth 驗證。請確認下列事項：
- 您已為要連結的 AI 用戶端 (例如 https://claude.ai/api/mcp/auth_callback、https://chatgpt.com/connector_platform_oauth_redirect 或 https://antigravity.google/oauth-callback) 新增適當的授權重新導向 URI。
- 您已在 OAuth 同意畫面中新增 https://www.googleapis.com/auth/adwords 範圍，方法是依序前往「APIs & Services」(API 和服務) >「OAuth consent screen」(OAuth 同意畫面) >「Data Access」(資料存取權)，然後點選「Add or remove scopes」(新增或移除範圍)。
- 如果 OAuth 同意畫面的發布狀態設為「測試」(預設)，您已將連線至 MCP 伺服器的 Google 帳戶新增為「測試使用者」，方法是依序前往「API 和服務」>「OAuth 同意畫面」>「目標對象」(「測試使用者」>「+ 新增使用者」)。
GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET：與 OAuth 用戶端 ID 對應的 OAuth 用戶端密鑰。
GOOGLE_ADS_MCP_BASE_URL：可存取 MCP 伺服器的公開基準網址 (例如 https://google-ads-mcp-xyz-uc.a.run.app)。由於 Google Cloud Run 會在初始部署期間產生這個網址，因此請先在不使用這個變數的情況下部署，然後在部署後更新服務。
FASTMCP_HOST：將此值設為 0.0.0.0，允許 FastMCP 接受來自所有 IP 位址的連線。

將服務部署至 Google Cloud Run：

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

Cloud Run 完成部署後，請擷取指派的服務網址，並使用 GOOGLE_ADS_MCP_BASE_URL 環境變數更新服務：

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

驗證與安全性模型

使用 --allow-unauthenticated 部署會停用 Cloud Run 的基礎架構層級 IAM 檢查 (roles/run.invoker)，因此外部 AI 用戶端不需 Google Cloud 服務帳戶權杖即可連線。驗證作業會改為委派給應用程式層：

提供 GOOGLE_ADS_MCP_OAUTH_CLIENT_ID 和 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET 時，MCP 伺服器會對所有傳入要求強制執行 Google OAuth 2.0，並以 HTTP 401 回應要求未經驗證的呼叫端。所有工具要求都必須在經過驗證的呼叫端 OAuth 身分下執行。
如果省略 --allow-unauthenticated，系統會強制執行 Cloud Run 基礎架構 IAM，要求呼叫端在每個要求中傳遞 Google Cloud OIDC 身分權杖。標準 AI 用戶端 (例如 Claude 和 ChatGPT) 是使用使用者 OAuth 進行驗證，而非 Google Cloud IAM 身分權杖，因此從這些平台直接連線時，需要使用應用程式層級 OAuth 的 --allow-unauthenticated。

設定 MCP 用戶端

部署完成後，請使用 Cloud Run 網址設定 MCP 用戶端。由於伺服器需要 OAuth 2.0 驗證，用戶端必須支援 MCP OAuth 流程，或提供授權的不記名權杖：

支援 OAuth 的用戶端：如果用戶端支援 MCP OAuth 探索 (例如 Antigravity)，連線至端點時會觸發驗證提示，要求使用者使用 Google 帳戶登入，並授予 https://www.googleapis.com/auth/adwords 範圍 (在 Google Cloud 控制台中列為 .../auth/adwords)。
第三方 AI 平台 (Claude、ChatGPT)：在用戶端的連接器或整合設定中，新增自訂連接器，指向 Cloud Run 網址和 /mcp 路徑 (例如 https://your-cloud-run-url.a.run.app/mcp)，選取 OAuth 2.0 驗證 (使用您自己的 OAuth 用戶端 ID 和用戶端密鑰)，並確認用戶端的回呼 URI 已新增至 OAuth 用戶端的授權重新導向 URI。(代管端點前測計畫的許可清單參與者，也可以參閱代管 MCP 設定指南)。
不支援 OAuth 的用戶端：不支援 HTTP OAuth 流程的用戶端會收到 HTTP 401 未授權回應。請改用本機 stdio 設定。

支援 OAuth 的用戶端 (例如 ~/.gemini/settings.json) 設定範例：

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

核心功能 (工具)

伺服器會提供專為帳戶探索和成效報表設計的工具：

list_accessible_customers：傳回已驗證使用者可存取的 Google Ads 客戶 ID 和帳戶名稱清單。
search：執行 GAQL 要求，擷取資源指標、預算和狀態。
get_resource_metadata：擷取 Google Ads API 資源類型的中繼資料，例如 "campaign"。

這有助於瞭解資料結構，以及哪些欄位可供查詢。

提示詞範例

詢問伺服器可執行的操作：

What can the google-ads-mcp server do?

詢問客戶：

What customers do I have access to?

詢問廣告活動相關問題：

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890

Google Ads MCP 伺服器：開發人員整合指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

社群資源和支援

技術總覽

主要規格

互動迴圈的運作方式

開始使用

必要條件

設定

選用：為代理提供技能和 Developer Assistant

在 Google Cloud 部署

必要條件

建構及推送 Docker 映像檔

部署到 Google Cloud Run

驗證與安全性模型

設定 MCP 用戶端

核心功能 (工具)

提示詞範例

後續步驟

Google Ads MCP 伺服器：開發人員整合指南