Máy chủ MCP của Google Ads: Hướng dẫn tích hợp cho nhà phát triển

Giao thức ngữ cảnh mô hình (MCP) là một tiêu chuẩn mở cho phép các Mô hình ngôn ngữ lớn (LLM) tương tác một cách an toàn với dữ liệu và ứng dụng bên ngoài. Máy chủ MCP của Google Ads cung cấp một cầu nối chuẩn hoá đến Google Ads API, cho phép các tác nhân AI phân tích và truy xuất dữ liệu chiến dịch bằng ngôn ngữ tự nhiên.

Tài nguyên và dịch vụ hỗ trợ của cộng đồng

Tổng quan về kỹ thuật

Bằng cách triển khai máy chủ MCP này, bạn không cần phải viết "mã kết nối" tuỳ chỉnh để xác thực Google Ads API, tìm nạp tài nguyên và phân tích cú pháp dữ liệu. Máy chủ hiển thị các công cụ cụ thể mà LLM có thể tự động khám phá và gọi.

Thông số kỹ thuật chính

  • Giao thức: MCP (Giao thức ngữ cảnh mô hình)
  • Chế độ: Chỉ có thể đọc (bản phát hành hiện tại)
  • Ngôn ngữ: Python
  • Truyền tải: Đầu vào/đầu ra chuẩn (stdio) hoặc HTTP có thể truyền trực tuyến (streamable-http / Cloud Run)
  • Xác thực: OAuth 2.0 hoặc tài khoản dịch vụ

Cách hoạt động của vòng lặp tương tác

  1. Yêu cầu: Người dùng gửi một cụm từ tìm kiếm, chẳng hạn như "Hiệu suất chiến dịch của tôi trong tuần này như thế nào?".
  2. Khám phá: LLM kiểm tra các công cụ hiện có và xác định khả năng tìm kiếm google-ads-mcp.
  3. Thực thi: Máy chủ MCP thực thi logic Python cơ bản để truy vấn Google Ads API.
  4. Chèn ngữ cảnh: Kết quả có cấu trúc được trả về cửa sổ ngữ cảnh của LLM.
  5. Câu trả lời: LLM tổng hợp dữ liệu thành một câu trả lời mà con người có thể đọc được.

Bắt đầu

Hãy làm theo các bước sau để định cấu hình và sử dụng máy chủ MCP của Google Ads.

Điều kiện tiên quyết

Trước khi định cấu hình, hãy đảm bảo bạn có thông tin đăng nhập sau đây từ bảng điều khiển Google Cloud:

  • Mã dự án: Mã dự án của bạn trên Google Cloud (GOOGLE_PROJECT_ID). Kiểm tra trang tổng quan về Google Ads API để đảm bảo dự án của bạn có cấp độ truy cập Explorer, cấp độ truy cập Cơ bản hoặc cấp độ truy cập Tiêu chuẩn. Nếu chưa, hãy đăng ký một trong các cấp truy cập này. Xin lưu ý rằng mã của nhà phát triển (GOOGLE_ADS_DEVELOPER_TOKEN) đã ngừng hoạt động vào ngày 9 tháng 9 năm 2026 và không còn bắt buộc trong phiên bản mới nhất của máy chủ MCP Google Ads vì các cấp truy cập API được liên kết với dự án trên đám mây của Google.
  • Thông tin xác thực OAuth: Một cặp Mã ứng dụng khách/Khoá bí mật của ứng dụng khách OAuth 2.0 hoặc một bộ thông tin xác thực mặc định của ứng dụng.

Cấu hình

Để tích hợp máy chủ vào một máy chủ lưu trữ tương thích với MCP, hãy thêm mục sau vào tệp cấu hình MCP của máy chủ lưu trữ (chẳng hạn như settings.json) và trỏ GOOGLE_APPLICATION_CREDENTIALS đến tệp JSON ADC của bạn (hoặc định cấu hình ADC mặc định bằng gcloud auth application-default login). Nếu truy cập vào tài khoản thông qua tài khoản người quản lý, bạn cũng có thể đặt GOOGLE_ADS_LOGIN_CUSTOMER_ID. Hãy tham khảo tài liệu của máy chủ lưu trữ để biết vị trí và tên tệp chính xác của cấu hình này.

{
  "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"
      }
    }
  }
}

Triển khai trên Google Cloud

Thay vì lưu trữ máy chủ MCP này trên máy, bạn có thể lưu trữ máy chủ này trên Google Cloud Run hoặc trên bất kỳ cơ sở hạ tầng nào khác dựa trên đám mây. Điều này rất hữu ích nếu bạn muốn chia sẻ máy chủ giữa các tác nhân khác nhau hoặc chạy máy chủ dưới dạng dịch vụ web.

Điều kiện tiên quyết

  1. Một dự án trên Google Cloud.

  2. Công cụ dòng lệnh gcloud đã được cài đặt, xác thực và định cấu hình với một dự án đang hoạt động:

    gcloud config set project YOUR_PROJECT_ID

Tạo và đẩy một hình ảnh Docker

Bạn có thể dùng Cloud Build để tạo và đẩy hình ảnh vào Artifact Registry mà không cần cài đặt Docker cục bộ.

  1. Tạo kho lưu trữ trong Artifact Registry:

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

  2. Chuyển đến thư mục dự án:

    cd <full path>/google-ads-mcp

  3. Tạo và gửi hình ảnh:

    gcloud builds submit \
  --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    Xin lưu ý rằng bạn phải thực hiện bước này bất cứ khi nào muốn cập nhật máy chủ đã triển khai lên phiên bản mới nhất.

Triển khai trên Google Cloud Run

Hãy nhớ đặt các biến môi trường bắt buộc:

  • GOOGLE_PROJECT_ID: Mã dự án trên Google Cloud của bạn, có các cấp truy cập API thích hợp.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Mã ứng dụng khách OAuth 2.0 (được định cấu hình dưới dạng Ứng dụng web trong dự án trên đám mây Google của bạn) để xác thực OAuth ở cấp ứng dụng. Đảm bảo rằng:
    • Bạn đã thêm các URI chuyển hướng được uỷ quyền thích hợp cho mọi ứng dụng AI mà bạn dự định kết nối (chẳng hạn như https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect hoặc https://antigravity.google/oauth-callback).
    • Bạn đã thêm phạm vi https://www.googleapis.com/auth/adwords vào màn hình xin phép bằng OAuth trong phần API và dịch vụ > Màn hình xin phép bằng OAuth > Quyền truy cập vào dữ liệu (Thêm hoặc xoá phạm vi).
    • Nếu trạng thái xuất bản màn hình xin phép OAuth của bạn được đặt thành Đang thử nghiệm (mặc định), thì bạn đã thêm Tài khoản Google kết nối với máy chủ MCP làm Người dùng thử nghiệm trong phần API và dịch vụ > Màn hình xin phép OAuth > Đối tượng (Người dùng thử nghiệm > + Thêm người dùng).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Khoá bí mật ứng dụng OAuth tương ứng với Mã ứng dụng OAuth.
  • GOOGLE_ADS_MCP_BASE_URL: URL cơ sở công khai mà máy chủ MCP của bạn có thể truy cập (ví dụ: https://google-ads-mcp-xyz-uc.a.run.app). Vì Google Cloud Run tạo URL này trong quá trình triển khai ban đầu, nên trước tiên, hãy triển khai mà không có biến này, sau đó cập nhật dịch vụ sau khi triển khai.
  • FASTMCP_HOST: Đặt giá trị này thành 0.0.0.0 để cho phép FastMCP chấp nhận kết nối từ tất cả địa chỉ IP.

Triển khai dịch vụ lên 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"

Sau khi Cloud Run hoàn tất quá trình triển khai, hãy truy xuất URL dịch vụ được chỉ định và cập nhật dịch vụ bằng biến môi trường 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"

Mô hình xác thực và bảo mật

Việc triển khai bằng --allow-unauthenticated sẽ vô hiệu hoá chế độ kiểm tra IAM ở cấp cơ sở hạ tầng của Cloud Run (roles/run.invoker) để các ứng dụng AI bên ngoài có thể kết nối mà không cần mã thông báo tài khoản dịch vụ Google Cloud. Thay vào đó, việc xác thực được uỷ quyền cho lớp ứng dụng:

  • Khi GOOGLE_ADS_MCP_OAUTH_CLIENT_ID và GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET được cung cấp, máy chủ MCP sẽ thực thi Google OAuth 2.0 trên tất cả các yêu cầu đến, thách thức những người gọi chưa được xác thực bằng phản hồi HTTP 401. Tất cả yêu cầu của công cụ đều được thực thi nghiêm ngặt theo danh tính OAuth của phương thức gọi đã xác thực.
  • Việc bỏ qua --allow-unauthenticated sẽ thực thi IAM cơ sở hạ tầng của Cloud Run, yêu cầu phương thức gọi truyền mã thông báo nhận dạng OIDC của Google Cloud với mỗi yêu cầu. Vì các ứng dụng AI tiêu chuẩn (chẳng hạn như Claude và ChatGPT) xác thực bằng OAuth của người dùng cuối thay vì mã thông báo danh tính Cloud IAM của Google Cloud, nên các kết nối trực tiếp từ những nền tảng này yêu cầu --allow-unauthenticated có OAuth ở cấp ứng dụng.

Định cấu hình ứng dụng MCP

Sau khi triển khai, hãy định cấu hình ứng dụng MCP bằng URL Cloud Run. Vì máy chủ yêu cầu xác thực OAuth 2.0, nên ứng dụng phải hỗ trợ quy trình OAuth của MCP hoặc cung cấp mã thông báo truy cập Bearer được uỷ quyền:

  • Ứng dụng hỗ trợ OAuth: Đối với các ứng dụng hỗ trợ tính năng khám phá OAuth của MCP (chẳng hạn như Antigravity), việc kết nối với điểm cuối sẽ kích hoạt lời nhắc xác thực để đăng nhập bằng Google và cấp phạm vi https://www.googleapis.com/auth/adwords (được liệt kê là .../auth/adwords trong Google Cloud Console).
  • Nền tảng AI bên thứ ba (Claude, ChatGPT): Trong phần cài đặt trình kết nối hoặc chế độ tích hợp của ứng dụng khách, hãy thêm một trình kết nối tuỳ chỉnh trỏ đến URL Cloud Run của bạn bằng đường dẫn /mcp (ví dụ: https://your-cloud-run-url.a.run.app/mcp), chọn phương thức xác thực OAuth 2.0 (sử dụng Mã ứng dụng khách OAuth và Khoá bí mật của ứng dụng khách của riêng bạn) và đảm bảo URI gọi lại của ứng dụng khách được thêm vào URI chuyển hướng được uỷ quyền của Ứng dụng OAuth. (Những người tham gia được đưa vào danh sách cho phép của chương trình thử nghiệm điểm cuối được lưu trữ cũng có thể tham khảo hướng dẫn thiết lập MCP được lưu trữ.)
  • Ứng dụng không hỗ trợ OAuth: Ứng dụng không hỗ trợ các luồng OAuth HTTP sẽ nhận được phản hồi HTTP 401 Không được phép. Đối với những công cụ này, hãy sử dụng cấu hình stdio cục bộ.

Ví dụ về cấu hình cho một ứng dụng có hỗ trợ OAuth (ví dụ: ~/.gemini/settings.json):

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

Các chức năng cốt lõi (công cụ)

Máy chủ cung cấp các công cụ được thiết kế để khám phá tài khoản và báo cáo hiệu suất:

  • list_accessible_customers: Trả về danh sách mã khách hàng Google Ads và tên tài khoản mà người dùng đã xác thực có thể truy cập.
  • search: Thực thi các yêu cầu Ngôn ngữ truy vấn của Google Ads (GAQL) để tìm nạp các chỉ số về tài nguyên, ngân sách và trạng thái.

  • get_resource_metadata: Truy xuất siêu dữ liệu về một loại tài nguyên của Google Ads API, ví dụ: "campaign".

    Điều này giúp bạn hiểu được cấu trúc của dữ liệu và những trường có thể truy vấn.

Câu lệnh mẫu để bắt đầu

Hỏi xem máy chủ có thể làm gì:

What can the google-ads-mcp server do?

Hỏi về khách hàng:

What customers do I have access to?

Hỏi về chiến dịch:

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