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 bối 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 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

• Kho lưu trữ GitHub: Tìm bản minh hoạ, ví dụ và báo cáo lỗi hoặc đề xuất tính năng trong kho lưu trữ google-ads-mcp.

  Sử dụng thẻ Vấn đề để báo cáo lỗi và yêu cầu về tính năng.

• Cộng đồng: Tham gia kênh #ads-api-ai-tools trên Google Advertising Community Discord.

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âu hỏi, 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ụ có sẵn và xác định các chức năng tìm kiếm của 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ó các thông tin xác thực sau đây trong Google Cloud Console:

• Mã dự án: Mã dự án của bạn trên Google Cloud (GOOGLE_PROJECT_ID). Hãy kiểm tra trang tổng quan về Google Ads API để đảm bảo rằng dự án của bạn có quyền truy cập Explorer, quyền truy cập Cơ bản hoặc quyền 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 cần thiết trong phiên bản mới nhất của máy chủ MCP của 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"
      }
    }
  }
}

Không bắt buộc: Trang bị cho tác nhân các kỹ năng và Trợ lý nhà phát triển

Máy chủ MCP của Google Ads cấp cho ứng dụng AI của bạn quyền chỉ có thể đọc đối với dữ liệu tài khoản theo thời gian thực. Để giúp tác nhân của bạn tạo các truy vấn Ngôn ngữ truy vấn Google Ads (GAQL) hợp lệ, chẩn đoán các thay đổi về hiệu suất tài khoản và tạo mã thư viện ứng dụng, hãy kết hợp máy chủ MCP với các công cụ đồng hành sau:

• Kỹ năng của tác nhân Google Ads API: Các mô-đun di động chứa hướng dẫn và quy trình làm việc dành riêng cho Google Ads API, bao gồm google-ads-api-mcp-setup, google-ads-api-account-diagnostics và google-ads-api-quickstart, giúp hướng dẫn tác nhân của bạn cách sử dụng máy chủ MCP của Google Ads một cách hiệu quả với mức hao tổn mã thông báo thấp hơn. Cài đặt các công cụ này bằng một lệnh duy nhất (yêu cầu Node.js) hoặc xem hướng dẫn về kỹ năng của tác nhân Google Ads API để biết các lựa chọn cho Antigravity, Claude Code, Codex và Cursor:

  npx skills add google/skills/skills/ads
  

• Trợ lý nhà phát triển Google Ads API: Một trình bổ trợ mô-đun cho Google Antigravity và Claude Code, cung cấp tính năng kiểm tra giản đồ Protobuf cục bộ, xác thực GAQL theo phương thức lập trình, tạo mã thư viện ứng dụng (bao gồm cả tập lệnh đột biến) và khắc phục sự cố về lượt chuyển đổi ngoại tuyến. Tìm hiểu cách hoạt động của tiện ích này trong bài viết Trợ lý nhà phát triển Google Ads API là gì? hoặc làm theo hướng dẫn cài đặt.

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 hình ảnh Docker

Bạn có thể sử dụng Cloud Build để tạo và đẩy hình ảnh lên Artifact Registry mà không cần cài đặt Docker trên máy.

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 đám mây của Google Cloud, có cấp truy cập API phù hợp.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Mã ứng dụng khách OAuth 2.0 (được định cấu hình là Ứ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 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 của ứ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 nơi có thể truy cập vào máy chủ MCP của bạn (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ẽ tắt tính năng 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ụ của Google Cloud. Thay vào đó, việc xác thực được uỷ quyền cho lớp ứng dụng:

• Khi bạn cung cấp GOOGLE_ADS_MCP_OAUTH_CLIENT_ID và GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, máy chủ MCP sẽ thực thi Google OAuth 2.0 trên tất cả các yêu cầu đến, từ chối những phương thức 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 Google Cloud IAM, 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 bằng 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 trong danh sách cho phép của chương trình thí điể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: Những ứng dụng không hỗ trợ quy trình HTTP OAuth sẽ nhận được phản hồi HTTP 401 Unauthorized (HTTP 401 Không được phép). Đối với các 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 GAQL để tìm nạp các chỉ số, ngân sách và trạng thái của tài nguyên.

• 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

Các bước tiếp theo

• Cài đặt kỹ năng của tác nhân phần mềm Google Ads API
• Tìm hiểu về Trợ lý nhà phát triển Google Ads API
• Cài đặt và sử dụng Trợ lý nhà phát triển Google Ads API