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 或服務帳戶

互動迴圈的運作方式

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

開始使用

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

必要條件

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

• 專案 ID：您的 Google Cloud 專案 ID (GOOGLE_PROJECT_ID)。請查看 Google Ads API 總覽頁面，確認專案具有探索者存取權、基本存取權或標準存取權。如果沒有，請申請其中一個存取層級。請注意，開發人員權杖 (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"
      }
    }
  }
}

在 Google Cloud 上部署

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

必要條件

1. Google Cloud 專案。

2. 已安裝 gcloud 指令列工具、完成驗證，並設定有效專案：

   gcloud config set project YOUR_PROJECT_ID
   

建構及推送 Docker 映像檔

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

1. 在 Artifact Registry 中建立存放區：

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

2. 前往專案目錄：

   cd <full path>/google-ads-mcp
   

3. 建構並提交映像檔：

   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。
  • 您已在「APIs & Services」(API 和服務) >「OAuth consent screen」(OAuth 同意畫面) >「Data Access」(資料存取權) (「Add or remove scopes」(新增或移除範圍)) 下，將 https://www.googleapis.com/auth/adwords 範圍新增至 OAuth 同意畫面。
  • 如果 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。

注意： 使用 --allow-unauthenticated 部署時，「絕對不要」省略 GOOGLE_ADS_MCP_OAUTH_CLIENT_ID 和 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET。這些環境變數會觸發伺服器，從本機 stdio 模式切換至 streamable-http 傳輸。如果沒有這些憑證，伺服器就無法強制執行驗證，並會改用應用程式預設憑證 (ADC)，將容器的服務帳戶憑證公開給未經驗證的呼叫端。

設定 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 URL 的自訂連接器，並使用 /mcp 路徑 (例如 https://your-cloud-run-url.a.run.app/mcp)，選取 OAuth 2.0 驗證 (使用您自己的 OAuth 用戶端 ID 和用戶端密鑰)，並確保用戶端的重新導向 URI 已新增至 OAuth 用戶端的授權重新導向 URI。(代管端點試用計畫的許可清單參與者也可以參閱代管 MCP 設定指南)。
• 不支援 OAuth 的用戶端：不支援 HTTP OAuth 流程的用戶端會收到 HTTP 401 Unauthorized 回應。請改用本機 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：執行 Google Ads 查詢語言 (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