Hãy thử máy chủ MCP cho Google Analytics. Cài đặt từ GitHub và xem thông báo để biết thêm thông tin chi tiết.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Dùng thử máy chủ MCP của Google Analytics

Máy chủ Giao thức bối cảnh mô hình (MCP) của Google Analytics cho phép bạn kết nối dữ liệu Google Analytics với các mô hình ngôn ngữ lớn (LLM) và tác nhân AI, chẳng hạn như Gemini. Bạn có thể sử dụng máy chủ MCP để truy vấn báo cáo bằng ngôn ngữ tự nhiên, kiểm tra cấu hình tài sản và xây dựng tác nhân phân tích tuỳ chỉnh.

Thiết lập máy chủ MCP Xem trên GitHub Xem hướng dẫn thiết lập

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

Trước khi định cấu hình máy chủ MCP của Google Analytics, hãy hoàn tất các yêu cầu sau:

Cài đặt Python và trình chạy gói:
- Cài đặt Python 3.10 trở lên.
- Cài đặt pipx hoặc uv (uvx) để chạy máy chủ MCP trong một môi trường Python tách biệt.
Bật API Google Analytics trong :
- Tạo hoặc chọn một dự án.
- Bật cả Google Analytics Admin API (analyticsadmin.googleapis.com) và Google Analytics Data API (analyticsdata.googleapis.com) trong dự án của bạn:
```
gcloud services enable analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project=YOUR_PROJECT_ID
```
Cấp quyền truy cập vào tài sản Google Analytics:
- Trong giao diện người dùng của Google Analytics, hãy cấp cho tài khoản người dùng hoặc tài khoản dịch vụ của bạn ít nhất là vai trò Người xem (roles/analytics.viewer) đối với tài sản Google Analytics mục tiêu. Để biết hướng dẫn, hãy xem bài viết Quản lý quyền truy cập và quy định hạn chế về dữ liệu.

Thiết lập phương thức xác thực

Máy chủ MCP của Google Analytics xác thực bằng Thông tin xác thực mặc định của ứng dụng (ADC) với phạm vi OAuth 2.0 chỉ có quyền đọc của Google Analytics:

https://www.googleapis.com/auth/analytics.readonly

Bạn có thể định cấu hình ADC bằng tài khoản người dùng Google hoặc tài khoản dịch vụ.

Cách 1: Xác thực bằng thông tin đăng nhập của người dùng

Cài đặt và khởi động gcloud CLI.

Chạy gcloud auth application-default login với các phạm vi bắt buộc:

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

Nếu bạn sử dụng tệp cấu hình ứng dụng web hoặc ứng dụng OAuth 2.0 đã tải xuống cho máy tính (xem phần Quản lý ứng dụng OAuth), hãy truyền --client-id-file:

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file=YOUR_CLIENT_JSON_FILE

Khi lệnh hoàn tất, hãy sao chép đường dẫn thông tin xác thực được in ra bảng điều khiển (Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]). Bạn sẽ sử dụng đường dẫn này trong GOOGLE_APPLICATION_CREDENTIALS khi định cấu hình ứng dụng MCP.

Cách 2: Xác thực bằng tài khoản dịch vụ

Cách xác thực bằng một tài khoản dịch vụ có quyền Người xem đối với tài sản Google Analytics:

Tệp khoá JSON của tài khoản dịch vụ: Đặt GOOGLE_APPLICATION_CREDENTIALS trong cấu hình ứng dụng MCP thành đường dẫn tuyệt đối của tệp JSON của tài khoản dịch vụ.

Mạo danh tài khoản dịch vụ: Tạo thông tin xác thực ADC bằng cách mạo danh tài khoản dịch vụ bằng CLI gcloud:

gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

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

Máy chủ được xuất bản trên PyPI dưới dạng analytics-mcp và hiển thị cả tập lệnh bảng điều khiển analytics-mcp và google-analytics-mcp.

Trong các cấu hình sau, hãy thay thế:

PATH_TO_CREDENTIALS_JSON bằng đường dẫn tuyệt đối đến tệp JSON của ADC hoặc tài khoản dịch vụ.
YOUR_PROJECT_ID bằng mã dự án mà bạn đã bật API Google Analytics.

Antigravity CLI và Antigravity IDE

Cài đặt Antigravity CLI hoặc Antigravity IDE.

Thêm máy chủ analytics-mcp vào ~/.gemini/config/mcp_config.json (hoặc .agents/mcp_config.json trong không gian làm việc của bạn):

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Xác minh rằng analytics-mcp đã được kết nối:
- Antigravity CLI: Chạy agy, sau đó nhập /mcp để xem các máy chủ MCP đã định cấu hình.
- Antigravity IDE: Mở phần Cài đặt > Tuỳ chỉnh > Máy chủ MCP đã cài đặt rồi nhấp vào Làm mới.

Claude Desktop và Claude Code

Đối với Claude Desktop, hãy thêm máy chủ vào tệp claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json trên macOS hoặc %APPDATA%\Claude\claude_desktop_config.json trên Windows):

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Đối với Claude Code, hãy đăng ký máy chủ bằng công cụ dòng lệnh:

claude mcp add analytics-mcp \
  --scope user \
  -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
  -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  -- pipx run analytics-mcp

Con trỏ

Thêm máy chủ vào .cursor/mcp.json trong thư mục dự án (hoặc ~/.cursor/mcp.json cho cấu hình chung). Bạn có thể gọi google-analytics-mcp bằng uvx hoặc pipx:

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Để chạy phiên bản đang phát triển mới nhất trực tiếp từ GitHub bằng uvx, hãy cập nhật "args":

"args": [
  "--from",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

Ngoài ra, để sử dụng pipx, hãy thay đổi "command" thành "pipx" và đặt "args" thành:

"command": "pipx",
"args": [
  "run",
  "--spec",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

Các công cụ MCP hiện có

Máy chủ MCP của Google Analytics sử dụng API Quản trị và API Dữ liệu phiên bản 1 để hiển thị các công cụ chỉ có quyền đọc cho ứng dụng MCP của bạn:

Khám phá tài khoản và tài sản (API Quản trị):
- get_account_summaries: Liệt kê các tài khoản và tài sản Google Analytics mà người dùng đã xác thực có thể truy cập (accountSummaries.list).
- get_property_details: Trả về thông tin chi tiết về cấu hình cho một tài sản Google Analytics cụ thể (properties.get).
- list_google_ads_links: Liệt kê các mối liên kết với tài khoản Google Ads cho một tài sản (properties.googleAdsLinks.list).
- list_property_annotations: Liệt kê các chú thích được định cấu hình cho một tài sản (properties.reportingDataAnnotations.list).
Báo cáo và kiểm tra giản đồ (Data API phiên bản 1):
- get_custom_dimensions_and_metrics: Truy xuất các phương diện tuỳ chỉnh và chỉ số tuỳ chỉnh được xác định cho một tài sản (getMetadata).
- run_report: Chạy báo cáo Google Analytics chuẩn (runReport).
- run_realtime_report: Chạy báo cáo theo thời gian thực của Google Analytics (runRealtimeReport).
- run_funnel_report: Chạy báo cáo khám phá phễu của Google Analytics (runFunnelReport).
- run_conversions_report: Chạy báo cáo hiệu suất lượt chuyển đổi (runConversionsReport).

Câu lệnh mẫu

Sau khi kết nối, hãy thử đặt cho trợ lý AI những câu hỏi như:

Tôi đã có bao nhiêu người dùng vào hôm qua?
Những sản phẩm nào bán chạy nhất của tôi vào hôm qua?
Tôi có ngân sách tiếp thị là 5.000 USD/tháng và cần tăng doanh thu. Giúp tôi tạo một kế hoạch tiếp thị dựa trên dữ liệu.
Những phương diện và chỉ số tuỳ chỉnh nào được định cấu hình trong tài sản của tôi?
Những sự kiện phổ biến nhất trong tài sản Google Analytics của tôi trong 90 ngày qua là gì?

Khắc phục sự cố

Hãy sử dụng danh sách kiểm tra sau đây để giải quyết các lỗi thiết lập và lỗi thời gian chạy phổ biến:

403 PERMISSION_DENIED (API chưa được bật hoặc không có đủ quyền đối với tài sản):
- Xác nhận rằng cả Google Analytics Admin API (analyticsadmin.googleapis.com) và Google Analytics Data API (analyticsdata.googleapis.com) đều được bật trong dự án do GOOGLE_CLOUD_PROJECT chỉ định.
- Xác minh rằng người dùng hoặc tài khoản dịch vụ xác thực có ít nhất vai trò Người xem (roles/analytics.viewer) đối với tài sản Google Analytics mục tiêu trong giao diện người dùng Google Analytics.
- Nếu trạng thái lỗi cho biết Request had insufficient authentication scopes, hãy chạy lại gcloud auth application-default login với phạm vi https://www.googleapis.com/auth/analytics.readonly và https://www.googleapis.com/auth/cloud-platform.
Thiếu dự án hạn mức (GOOGLE_CLOUD_PROJECT) hoặc 403 ACCESS_NOT_CONFIGURED:
- Các yêu cầu được xác thực bằng thông tin xác thực ADC của người dùng cần có một dự án hạn mức đã bật API Google Analytics. Đặt "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" trong cấu hình env của máy chủ MCP hoặc đặt dự án hạn mức trên tệp ADC:
```
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```
Không tìm thấy tệp thông tin xác thực hoặc 401 UNAUTHENTICATED:
- Sử dụng đường dẫn tuyệt đối cho GOOGLE_APPLICATION_CREDENTIALS (ví dụ: /Users/username/.config/gcloud/application_default_credentials.json). Tránh các biến ~ hoặc $HOME, vì nhiều máy chủ MCP không mở rộng các biến shell bên trong tệp cấu hình JSON.
- Chạy lại gcloud auth application-default login nếu thông tin đăng nhập của người dùng đã hết hạn.
Không khởi chạy được máy chủ (lỗi spawn pipx ENOENT, uvx: command not found hoặc lỗi phiên bản Python):
- Xác nhận rằng bạn đã cài đặt Python 3.10 trở lên (python3 --version).
- Các ứng dụng GUI dành cho máy tính (chẳng hạn như Claude Desktop và Cursor) thường không kế thừa PATH shell tương tác của bạn. Thay thế "pipx" hoặc "uvx" trong "command" bằng đường dẫn nhị phân tuyệt đối do which pipx hoặc which uvx trả về (ví dụ: /opt/homebrew/bin/pipx hoặc /Users/username/.local/bin/pipx).