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 tiêu chuẩn cho 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 dính" tuỳ chỉnh để xác thực API Google Ads, tìm nạp tài nguyên và phân tích cú pháp dữ liệu. Máy chủ này cung cấp các công cụ cụ thể mà LLM có thể tự động khám phá và gọi.

Quy cách chính

  • Giao thức: MCP (Giao thức ngữ cảnh mô hình)
  • Chế độ: Chỉ có thể đọc (phiên bản hiện tại)
  • Ngôn ngữ: Python
  • Vận chuyển: Đầu vào/đầu ra tiêu chuẩn (stdio) hoặc HTTP/SSE (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. Phản hồi: LLM tổng hợp dữ liệu thành 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ừ Google Cloud Console:

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, rồi 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 các 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. Tham khảo tài liệu của máy chủ lưu trữ để biết chính xác vị trí và tên tệp 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 cục bộ, bạn có thể lưu trữ trên Google Cloud Run hoặc trên bất kỳ cơ sở hạ tầng dựa trên đám mây nào khác. Điều này hữu ích nếu bạn muốn chia sẻ máy chủ trên nhiều tác nhân hoặc kích hoạt 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ài đặt, được xác thực và có một dự án đang hoạt động được định cấu hình:

    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

Đảm bảo bạn đã thiết lập 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 OAuth mà bạn muốn máy chủ MCP sử dụng.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Khoá bí mật của ứng dụng OAuth mà bạn muốn máy chủ MCP sử dụng.
  • GOOGLE_ADS_MCP_BASE_URL: URL cơ sở mà máy chủ MCP của bạn có thể truy cập; URL này sẽ được Google Cloud Run tự động chỉ định sau lần triển khai đầu tiên. Bạn có thể cập nhật các biến môi trường 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 các kết nối từ tất cả địa chỉ IP.
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,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

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

Sau khi triển khai, hãy cập nhật cấu hình ứng dụng MCP (ví dụ: ~/.gemini/settings.json) để sử dụng URL Cloud Run.

{
  "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ủ này 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 Google Ads API, chẳng hạn như "campaign".

    Điều này rất hữu ích để hiểu cấu trúc của dữ liệu và những trường có sẵn để 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