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

Model Context Protocol (MCP) 是一項開放標準，可讓大型語言模型 (LLM) 安全地與外部資料和應用程式互動。Google Ads MCP 伺服器提供標準化橋梁，可連結至 Google Ads API。AI 代理可透過自然語言，擷取及分析帳戶資料、建立素材資源、上傳影片，以及管理標籤。

社群資源和支援

技術總覽

整合 Google Ads MCP 伺服器後，就不需要編寫自訂程式碼，來處理 Google Ads API 驗證、資源擷取、資料剖析，以及支援的素材資源或標籤異動。伺服器會公開可呼叫的工具和參考資源 (請參閱「核心功能」)，LLM 可檢查及叫用這些工具和資源。

主要規格

  • 通訊協定：MCP (Model Context Protocol)
  • 模式：讀取和部分變更 (素材資源建立、影片上傳和標籤管理，採用提議和確認驗證，或可設定的唯讀模式)
  • 語言：Python 3.10 以上版本
  • 傳輸：標準輸入內容/輸出 (stdio) 或可串流 HTTP (Cloud Run 上的 streamable-http)
  • 驗證：本機 stdio 的應用程式預設憑證 (OAuth 2.0 使用者憑證或服務帳戶)，或遠端 HTTP 的 OAuth 2.0 網頁應用程式憑證

互動迴圈的運作方式

  1. 要求：您提交提示，例如「本週廣告活動成效如何？」或「為夏季特賣建立摘要素材資源」。
  2. 探索：LLM 檢查可用的工具和資源，並選取相符的 google-ads-mcp 工具。
  3. 執行或模擬測試驗證：讀取工具會直接查詢 Google Ads API。Mutate 工具會先在建議模式 (validate_only=True) 下執行，驗證輸入內容，但不提交變更 (請參閱「建議和確認安全工作流程」)。
  4. 脈絡注入：MCP 伺服器會將結構化查詢結果，或建議的 change_items 項目和驗證 checksum 摘要，傳回 LLM 的脈絡視窗。
  5. 回覆和確認：LLM 會提供答案，或要求您確認建議的變更。核准後，LLM 會再次呼叫 mutate 工具，並提供 validate_only=False 和相符的 checksum 值，以提交變更。

開始使用

請按照下列步驟，在本機設定及執行 Google Ads MCP 伺服器。如要改為部署共用遠端服務，請參閱「在 Google Cloud 上部署」。

必要條件

設定伺服器前，請先在本機環境和 Google Cloud 控制台完成下列必要條件：

  • Google Cloud 專案：建立或選取已啟用 Google Ads API 的 Google Cloud 專案。啟用 API 後，您將獲得測試存取權，可針對測試帳戶測試讀取和變更工作流程。如要存取正式版帳戶，請前往 Google Ads API 總覽頁面，查看是否具備 Explorer、基本版或標準存取權，或申請其中一種存取層級。否則，正式環境呼叫會失敗，並傳回 AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION 錯誤。Google 將於 2026 年 9 月 9 日停用開發人員權杖 (GOOGLE_ADS_DEVELOPER_TOKEN)。擁有 OAuth 用戶端或服務帳戶的 Google Cloud 專案，會決定您的 API 存取層級。
  • 憑證：本機 stdio 模式會使用 OAuth 2.0 用戶端密鑰 JSON 檔案或雲端專案中服務帳戶的應用程式預設憑證 (ADC) 進行驗證。視需要設定 GOOGLE_CLOUD_PROJECT 環境變數，指定預設配額或 ADC 專案。遠端 streamable-http 部署作業則需要 OAuth 2.0 網頁應用程式用戶端 ID 和用戶端密鑰 (請參閱「部署至 Google Cloud Run」)。
  • 本機軟體 (適用於 stdio 模式)：安裝 Python 3.10 以上版本、pipx 和 gcloud 指令列工具 (用於產生使用者 ADC 檔案)。

設定

  1. 使用已啟用 API 的 Google Cloud 專案中的 OAuth 用戶端，產生應用程式預設憑證 (ADC)，並加入 Google Ads API 範圍：

    gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=PATH_TO_CLIENT_SECRET_JSON

    更改下列內容：

    • PATH_TO_CLIENT_SECRET_JSON：OAuth 2.0 用戶端密鑰 JSON 檔案的路徑。

    這個指令會輸出 Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] (例如 Linux 和 macOS 上的 ~/.config/gcloud/application_default_credentials.json)。如要改用服務帳戶進行驗證，請略過這個步驟，並將 GOOGLE_APPLICATION_CREDENTIALS 指向服務帳戶金鑰 JSON 檔案，或將 --impersonate-service-account 傳遞至 gcloud auth application-default login。

  2. 將伺服器新增至主機的 MCP 設定檔 (例如 ~/.gemini/config/mcp_config.json、~/.gemini/settings.json 或 ~/.claude/settings.json)：

    {
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "google-ads-mcp==0.0.6",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON"
      }
    }
  }
}

    更改下列內容：

    • PROJECT_ID：您的 Google Cloud 專案 ID。
    • PATH_TO_CREDENTIALS_JSON：步驟 1 列印的 ADC JSON 檔案路徑，或服務帳戶金鑰 JSON 檔案路徑。使用預設 gcloud ADC 檔案位置時，可以省略 GOOGLE_APPLICATION_CREDENTIALS。

    如要透過管理員帳戶存取客戶帳戶，請在 env 中設定 GOOGLE_ADS_LOGIN_CUSTOMER_ID (10 位數，不含連字號)，或在個別工具呼叫中傳遞 login_customer_id 參數。

選用：為代理新增技能和開發人員助理

Google Ads MCP 伺服器可讓 AI 用戶端即時存取帳戶報表資料，以及素材資源建立、影片上傳和標籤管理工具。將 MCP 伺服器與下列隨附工具搭配使用，可協助代理建構有效的 Google Ads 查詢語言 (GAQL) 查詢，並診斷帳戶成效變化。這些工具也會產生用戶端程式庫程式碼，例如將建立的素材資源連結至廣告活動，或執行其他不支援的異動：

  • 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？」一文，或按照安裝指南操作。

核心功能

以下各節說明伺服器的讀取工具、部分變動工具和參考資源。從 v0.0.6 開始，工具預設會使用類別命名空間前置字元 (例如 search_search) 註冊。從無前置字元的版本升級提示或許可清單時，請更新工具名稱，或在 tools_config.yaml 中設定空白前置字元 ("") (請參閱「設定工具命名空間和唯讀模式」)。

朗讀工具

  • customers_list_accessible_customers (工具 list_accessible_customers)：傳回已驗證使用者可直接存取的 Google Ads 客戶 ID。
  • search_search (工具 search)：根據結構化參數 (customer_id、resource 和 fields，以及選用的 conditions、orderings、limit 和 login_customer_id)，建構並執行 GAQL SearchStream 查詢，而非原始 GAQL 字串。每項查詢都會附加 PARAMETERS omit_unselected_resource_names=true，以擷取資源屬性、指標、區隔、預算和狀態。
  • metadata_get_resource_metadata (工具 get_resource_metadata)： 擷取 Google Ads API 資源類型 (例如 "campaign") 的可選取、可篩選和可排序屬性、指標和區隔。在呼叫 search_search 工具之前，請使用這項中繼資料找出有效的查詢欄位，包括在次要版本 (例如 v26.2) 中新增的指標和區隔。

Mutate 工具 (部分支援)

  • assets_create_asset (工具 create_asset)：建立獨立的 Google Ads 素材資源，並為 TEXT、IMAGE、YOUTUBE_VIDEO、SITELINK、CALLOUT 和 STRUCTURED_SNIPPET 素材資源類型設定專屬參數。針對其他可變動的 AssetService 類型 (例如 PRICE、PROMOTION、CALL 或 BUSINESS_MESSAGE)，傳遞 extra_params 字典，並在 SITELINK 素材資源的 sitelink_link_text 旁加入根層級 final_urls。本機檔案路徑 (image_asset_path) 僅適用於本機 stdio 模式。如果是遠端 HTTP 部署作業，請傳遞採用 Base64 編碼的 image_asset_data 參數，並將 image_asset_mime_type 設為 IMAGE_PNG、IMAGE_JPEG 或 IMAGE_GIF (最多 20 MB)。
  • assets_upload_video_asset (工具 upload_video_asset)：上傳本機影片檔案 (.3gp、.avi、.flv、.mkv、.mov、.mp4、.mpeg、.mpg、.ogg、.webm 或 .wmv) 至 YouTube，僅限透過 Google Ads API 的本機 stdio 模式。video_title 和 video_description 都是必要參數，隱私權預設為 UNLISTED (或在廣告主擁有的品牌頻道上，使用使用者 OAuth 時為 PUBLIC)。這項工具會傳回 Google Ads video_upload_id 值 (和資源名稱)，而非 11 個字元的 YouTube video_id。使用 search_search 工具查詢 you_tube_video_upload (依 you_tube_video_upload.video_upload_id 篩選)，直到 you_tube_video_upload.state = 'PROCESSED' 為止。然後將 you_tube_video_upload.video_id 做為 youtube_video_id 參數傳遞至 assets_create_asset (asset_type="YOUTUBE_VIDEO")。
  • labels_manage_labels (工具 manage_labels)：建立、更新及移除帳戶標籤，包括名稱、說明和十六進位背景顏色。
  • labels_manage_label_associations (工具 manage_label_associations)：支援 CAMPAIGN、CUSTOMER、AD_GROUP 和 AD_GROUP_CRITERION 資源的 CREATE 和 REMOVE 標籤關聯作業 (不支援 UPDATE)。如果是 CUSTOMER 資源，resource_id 為選用，預設值為 customer_id。為 AD_GROUP_CRITERION 資源傳遞複合 {ad_group_id}~{criterion_id} ID，並傳遞 resource_id 和 label_id 或 association_resource_name 來移除關聯。不支援廣告層級 AD_GROUP_AD 標籤。

參考資源

伺服器會公開四個唯讀 MCP 資源，無論 tools_config.yaml 設定為何，這些資源都會保持掛接狀態：

  • resource://discovery-document：Google Ads API 資源、服務方法和結構定義的 JSON REST 探索總覽。這項工具可與 metadata_get_resource_metadata 工具搭配使用，後者會傳回可選取、篩選及排序的 GAQL 查詢欄位。
  • resource://metrics：Google Ads API 指標的 HTML 參考文件。
  • resource://segments：Google Ads API 區隔的 HTML 參考文件。
  • resource://release-notes：HTML Google Ads API 版本資訊，涵蓋版本異動和新功能。

「提議並確認」安全工作流程

每個變更工具 (assets_create_asset、assets_upload_video_asset、labels_manage_labels 和 labels_manage_label_associations) 都會強制執行兩步驟的「提議和確認」工作流程，避免意外修改帳戶：

  1. Propose (validate_only=True，預設)：驗證輸入內容，但不提交變更。素材資源和標籤工具會執行 Google Ads API validate_only 模擬測試。由於 YouTubeVideoUploadService 沒有模擬測試模式，assets_upload_video_asset 會改為驗證本機檔案，並繫結其大小和修改時間戳記。每項工具都會傳回人類可讀的 change_items 項目，以及繫結至 customer_id 參數和要求酬載的無狀態 SHA-256 checksum 摘要。
  2. 確認 (validate_only=False)：代理通話呈現 change_items 清單並獲得您的核准後，會再次呼叫工具，並提供 validate_only=False、相同的 customer_id 參數和引數，以及步驟 1 的 checksum 值。伺服器會拒絕任何遺漏或不相符的核對和，然後才會變更帳戶。

設定工具命名空間和唯讀模式

伺服器會隨附預設的 tools_config.yaml 檔案，並啟用所有五個工具類別 (customers、search、metadata、labels 和 assets)。自訂 tools_config.yaml，選擇性啟用或停用個別工具或命名空間、變更或移除命名空間前置字元，或強制執行嚴格唯讀部署作業。

伺服器啟動時，會依下列順序解析 tools_config.yaml：

  1. GOOGLE_ADS_MCP_TOOLS_CONFIG 環境變數中的明確路徑 (建議用於本機 stdio 主機，其目前使用的目錄可能與專案資料夾不同)。
  2. 伺服器目前使用的目錄中的 tools_config.yaml 檔案。
  3. 套件隨附的預設 tools_config.yaml 檔案。

如果 GOOGLE_ADS_MCP_TOOLS_CONFIG 指向遺失的檔案，或任何解析的設定檔無效，伺服器會在啟動時引發錯誤，而非改用預設值。

下列最小 tools_config.yaml 檔案會強制執行嚴格的唯讀部署作業：

namespaces:
  customers: true
  search: true
  metadata: true
  labels: false
  assets: false

下列 tools_config.yaml 檔案會自訂前置字元，並篩選個別工具 (例如在 Cloud Run 上公開 base64 create_asset 工具，同時停用僅限本機的 upload_video_asset 工具)：

namespaces:
  # Default prefix ("customers_list_accessible_customers")
  customers: true

  # Empty prefix mounts unprefixed tool names ("search")
  search: ""

  # Custom prefix ("schema_get_resource_metadata")
  metadata: "schema"

  # Enable only specific tools in a multi-tool category
  assets:
    enabled_tools:
      - create_asset

提示詞範例

連線至伺服器後，請在 MCP 用戶端中嘗試下列提示。

詢問伺服器可執行的操作

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

建立資產、上傳影片及管理標籤

Create a callout asset with the text "Free Shipping" for account 1234567890

Upload /path/to/promo.mp4 with title "Summer Sale" and description "Summer promo video" for account 1234567890

Create a label named "Q4 Promo" with background color #34A853 and apply it to campaign 9876543210 in account 1234567890

在 Google Cloud 部署

如要與多個代理共用 MCP 伺服器，或將其做為網路服務執行，請在 Google Cloud Run 或其他雲端基礎架構供應商託管，而非在本機執行。

必要條件

  1. 已啟用 Google Ads API 的 Google Cloud 專案 (如需正式版權限規定，請參閱必要條件)。

  2. 已安裝 gcloud 指令列工具，並已完成驗證及設定，且有使用中的專案：

    gcloud config set project PROJECT_ID

    更改下列內容：

    • PROJECT_ID：您的 Google Cloud 專案 ID。

建構及推送 Docker 映像檔

使用 Cloud Build 建構容器映像檔，並推送至 Artifact Registry，不必在本機安裝 Docker：

  1. 在 Artifact Registry 建立存放區：

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

  2. 從 GitHub 存放區中的版本標記建構及提交映像檔 (如果您自訂 Dockerfile 或 tools_config.yaml，則從本機簽出的 . 建構及提交)：

    gcloud builds submit https://github.com/googleads/google-ads-mcp \
  --git-source-revision=v0.0.6 \
  --tag=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6

    更改下列內容：

    • PROJECT_ID：您的 Google Cloud 專案 ID。

    每當您更新 google-ads-mcp，或升級隨附的 google-ads Python 用戶端程式庫，以支援新的 Google Ads API 版本 (例如 v26.2) 時，請重新建構並重新部署映像檔。

部署到 Google Cloud Run

為 Cloud Run 服務設定下列環境變數和密鑰：

  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID：OAuth 2.0 網頁應用程式用戶端 ID，來自已啟用 API 的 Google Cloud 雲端專案，用於應用程式層級的 OAuth 驗證。完成下列 OAuth 設定步驟：
    • 為您打算連結的任何 AI 用戶端 (例如 https://claude.ai/api/mcp/auth_callback、https://chatgpt.com/connector_platform_oauth_redirect 或 https://antigravity.google/oauth-callback) 新增已授權的重新導向 URI。
    • 依序前往「API 和服務」>「OAuth 同意畫面」>「資料存取權」(「新增或移除範圍」)，將 https://www.googleapis.com/auth/adwords 範圍新增至 OAuth 同意畫面。
    • 如果 OAuth 同意畫面的發布狀態設為「測試」(預設)，請依序前往「API 和服務」>「OAuth 同意畫面」>「目標對象」，將連線至 MCP 伺服器的 Google 帳戶新增為「測試使用者」(「測試使用者」>「+ 新增使用者」)。
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET：與 OAuth 用戶端 ID 對應的 OAuth 用戶端密鑰。
  • GOOGLE_ADS_MCP_BASE_URL：MCP 伺服器的公開基準網址 (例如 https://google-ads-mcp-xyz-uc.a.run.app)。Cloud Run 會在初始部署期間指派這個網址，因此請先在不使用這個變數的情況下部署，然後再更新服務。
  • GOOGLE_ADS_MCP_JWT_SIGNING_KEY (建議用於多實體 Cloud Run)：永久密鑰，可在容器重新啟動和水平調整資源配置時簽署 FastMCP JWT。
  • GOOGLE_ADS_MCP_STORAGE_TYPE (建議用於多實體 Cloud Run)：OAuth 用戶端註冊和權杖的永久後端 (redis 搭配 GOOGLE_ADS_MCP_STORAGE_REDIS_URL 或 firestore)。由於現成的 v0.0.6 Dockerfile 只會安裝記憶體內後端，因此請先在自訂 Dockerfile 中安裝 py-key-value-aio[redis] 或 .[firestore]。如要使用 firestore，您也必須具備 Firestore 資料庫，以及 Cloud Run 服務帳戶的 roles/datastore.user IAM 角色。如要使用記憶體內儲存空間進行單一執行個體測試，請傳遞 --max-instances=1。
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID (選用)：工具呼叫省略 login_customer_id 參數時，使用的預設 10 位數管理員客戶 ID (不含連字號)。
  • GOOGLE_ADS_MCP_TOOLS_CONFIG (選用)：自訂 tools_config.yaml 檔案的容器路徑 (例如從 Secret Manager 掛接在 /etc/mcp/tools_config.yaml，強制執行唯讀模式，而不必重建映像檔)。請參閱「設定工具命名空間和唯讀模式」。

將 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET 和 GOOGLE_ADS_MCP_JWT_SIGNING_KEY 儲存在 Secret Manager，並將服務部署至 Google Cloud Run：

gcloud run deploy google-ads-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6 \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=CLIENT_ID" \
  --set-secrets="GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=MCP_OAUTH_CLIENT_SECRET:latest,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=MCP_JWT_SIGNING_KEY:latest"

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://CLOUD_RUN_SERVICE_URL"

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • CLIENT_ID：OAuth 2.0 網頁應用程式用戶端 ID。
  • MCP_OAUTH_CLIENT_SECRET：儲存 OAuth 2.0 用戶端密鑰的 Secret Manager 密鑰名稱。
  • MCP_JWT_SIGNING_KEY：儲存 JWT 簽署金鑰的 Secret Manager 密鑰名稱。
  • CLOUD_RUN_SERVICE_URL：指派給 Cloud Run 服務的主機名稱 (例如 google-ads-mcp-xyz-uc.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 後，伺服器會對每項要求強制執行 Google OAuth 2.0，並向未經驗證的呼叫端傳回 401 Unauthorized HTTP 狀態碼。每項工具呼叫都會在經過驗證的呼叫端 OAuth 身分下執行。
  • 如果省略 --allow-unauthenticated，呼叫端必須在每個要求中傳遞 Google Cloud OIDC 身分權杖。標準 AI 用戶端 (例如 Claude 和 ChatGPT) 使用使用者 OAuth，而非 Google Cloud IAM 權杖，因此直接連線需要 --allow-unauthenticated 搭配應用程式層級 OAuth。

設定 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)：在用戶端的連接器設定中，新增自訂連接器，並指向含有 /mcp 路徑的服務網址 (例如 https://google-ads-mcp-xyz-uc.a.run.app/mcp)。選取 OAuth 2.0 驗證，並提供 OAuth 用戶端 ID 和用戶端密鑰，然後確認用戶端的回呼 URI 位於 OAuth 用戶端的授權重新導向 URI 中。
  • 不支援 OAuth 的用戶端：不支援 HTTP OAuth 流程的用戶端會收到 401 Unauthorized HTTP 狀態碼。如果是這類用戶端，請改用本機 stdio 設定。

以下範例會在 ~/.gemini/settings.json 中設定 gemini 指令列工具 (如果是 ~/.gemini/config/mcp_config.json 中的 Google Antigravity，請將 "httpUrl" 替換為 "serverUrl" 或 "url")：

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://CLOUD_RUN_SERVICE_URL/mcp"
    }
  }
}

更改下列內容：

  • CLOUD_RUN_SERVICE_URL：指派給 Cloud Run 服務的主機名稱 (例如 google-ads-mcp-xyz-uc.a.run.app)。

後續步驟