Định cấu hình máy chủ MCP của Gmail

Gmail cung cấp một máy chủ Giao thức bối cảnh mô hình (MCP) từ xa, cho phép các tác nhân AI tương tác an toàn với dữ liệu Gmail. Bằng cách định cấu hình máy chủ MCP của Gmail, bạn cho phép các ứng dụng AI như Google Antigravity và Claude thực hiện các thao tác trong Gmail.

Máy chủ MCP của Gmail cung cấp một cách thức chuẩn hoá để các tác nhân AI:

  • Đọc dữ liệu: Tìm kiếm email, truy xuất chuỗi thư và liệt kê nhãn.
  • Thực hiện hành động: Tạo email nháp và gắn nhãn cho thư.
  • Tôn trọng tính bảo mật: Kế thừa các quyền và chế độ kiểm soát quản trị dữ liệu giống như người dùng.

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

Định cấu hình máy chủ MCP của Gmail

Để sử dụng máy chủ MCP của Gmail, bạn phải bật máy chủ này trong dự án trên đám mây của Google Cloud, sau đó định cấu hình ứng dụng MCP để kết nối với máy chủ đó.

Bật API

Để sử dụng máy chủ MCP của Gmail, bạn phải bật API sau trong dự án trên đám mây của Google:

  • API Gmail

CLI

gcloud services enable gmail.googleapis.com --project=PROJECT_ID

Thay thế PROJECT_ID bằng mã dự án trên đám mây của bạn.

Giao diện dòng lệnh

Bật các API trong Google Cloud Console:

Bật API

Bật dịch vụ MCP

Để bật các thành phần MCP cho Gmail, bạn phải bật dịch vụ sau trong dự án trên đám mây của Google:

  • Gmail MCP API

CLI

gcloud services enable gmailmcp.googleapis.com --project=PROJECT_ID

Thay thế PROJECT_ID bằng mã dự án trên đám mây của bạn.

Giao diện dòng lệnh

Bật các dịch vụ MCP trong Google Cloud Console:

Bật các dịch vụ MCP

Máy chủ MCP của Gmail sử dụng OAuth 2.0 để xác thực và uỷ quyền. Bạn phải định cấu hình màn hình xin phép bằng OAuth trước khi có thể tạo mã ứng dụng khách OAuth.

  1. Trong Google Cloud Console, hãy chuyển đến Google Auth Platform > Xây dựng thương hiệu.

    Chuyển đến phần Xây dựng thương hiệu

  2. Nếu đã định cấu hình Nền tảng xác thực của Google, bạn có thể định cấu hình các chế độ cài đặt sau đây cho Màn hình xin phép bằng OAuth trong phần Thương hiệu, Đối tượng, và Quyền truy cập dữ liệu. Nếu bạn thấy thông báo cho biết Nền tảng xác thực của Google chưa được định cấu hình, hãy nhấp vào Bắt đầu:

    1. Trong phần App Information (Thông tin ứng dụng), trong mục App name (Tên ứng dụng), hãy nhập Gmail MCP Server.
    2. Trong phần Email hỗ trợ người dùng, hãy chọn địa chỉ email của bạn hoặc một nhóm Google Groups phù hợp.
    3. Nhấp vào Tiếp theo.
    4. Trong phần Đối tượng, hãy chọn Nội bộ. Nếu bạn không thể chọn Nội bộ, hãy chọn Bên ngoài.
    5. Nhấp vào Tiếp theo.
    6. Trong phần Thông tin liên hệ, hãy nhập Địa chỉ email để bạn có thể nhận thông báo về mọi thay đổi đối với dự án của mình.
    7. Nhấp vào Tiếp theo.
    8. Trong phần Finish (Hoàn tất), hãy xem lại Chính sách dữ liệu người dùng của các dịch vụ API của Google và nếu bạn đồng ý, hãy chọn I agree to the Google API Services: User Data Policy (Tôi đồng ý với Chính sách dữ liệu người dùng của các dịch vụ API của Google).
    9. Nhấp vào Tiếp tục.
    10. Nhấp vào Tạo.
    11. Nếu bạn đã chọn Bên ngoài cho loại người dùng, hãy thêm người dùng thử nghiệm:
      1. Nhấp vào Đối tượng.
      2. Trong phần Người dùng thử nghiệm, hãy nhấp vào Thêm người dùng.
      3. Nhập địa chỉ email của bạn và mọi người dùng thử nghiệm được uỷ quyền khác, sau đó nhấp vào Lưu.

  3. Nhấp vào Truy cập dữ liệu > Thêm hoặc xoá phạm vi. Một bảng điều khiển sẽ xuất hiện cùng với danh sách phạm vi cho từng API mà bạn đã bật trong dự án trên đám mây của Google Cloud.

    1. Trong phần Thêm phạm vi theo cách thủ công, hãy dán các phạm vi cho Gmail Máy chủ MCP:

      • https://www.googleapis.com/auth/gmail.readonly
      • https://www.googleapis.com/auth/gmail.compose

    2. Nhấp vào Thêm vào bảng.

    3. Nhấp vào Cập nhật.

    4. Sau khi chọn các phạm vi mà ứng dụng của bạn yêu cầu, trên trang Truy cập dữ liệu, hãy nhấp vào Lưu.

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

Để thêm máy chủ MCP từ xa của Gmail vào ứng dụng MCP, hãy làm theo hướng dẫn dành cho ứng dụng của bạn.

Mã ứng dụng khách OAuth 2.0 do người dùng uỷ quyền gọi máy chủ MCP của Gmail phải được chọn Sử dụng ứng dụng khách này cho một tác nhân dựa trên AI trong Nền tảng xác thực của Google > Ứng dụng khách. Để cập nhật mã ứng dụng khách OAuth 2.0 hiện có, hãy chọn chế độ cài đặt này trong Nền tảng xác thực của Google > Ứng dụng, như mô tả trong phần Quản lý ứng dụng OAuth. Nếu bạn không thể thay đổi chế độ cài đặt này trên một ứng dụng khách hiện có hoặc nếu ứng dụng khách đó cũng hỗ trợ các tính năng không phải của tác nhân, hãy tạo một mã ứng dụng khách OAuth 2.0 mới cho tác nhân AI của bạn. Đối với các yêu cầu bị từ chối, tài khoản dịch vụ có quyền uỷ quyền trên toàn miền hoặc Google Apps Script, hãy xem phần Khắc phục sự cố.

Antigravity

Để thêm máy chủ MCP từ xa của Gmail vào Antigravity, hãy thêm cấu hình máy chủ vào tệp mcp_config.json của bạn. Các hướng dẫn này hỗ trợ Antigravity 2.0, Antigravity IDE và Antigravity CLI.

  1. Tạo mã ứng dụng khách và khoá bí mật OAuth 2.0:

    1. Trong Google Cloud Console, hãy chuyển đến Google Auth Platform (Nền tảng xác thực của Google) > Clients (Ứng dụng khách) > Create Client (Tạo ứng dụng khách).

      Chuyển đến phần Tạo ứng dụng

    2. Chọn Ứng dụng web làm loại ứng dụng.

    3. Nhập Tên.

    4. Trong mục URI chuyển hướng được uỷ quyền, hãy nhấp vào + Thêm URI, rồi thêm https://antigravity.google/oauth-callback vào trường URI.

    5. Chọn Sử dụng khách hàng này cho một tác nhân dựa trên AI.

    6. Nhấp vào Tạo rồi sao chép Mã ứng dụng khách và Khoá bí mật của ứng dụng khách.

  2. Mở hoặc tạo tệp cấu hình ~/.gemini/config/mcp_config.json.

  3. Thêm cấu hình mcpServers vào mcp_config.json:

    {
  "mcpServers": {
    "gmail": {
      "serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": {
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET"
      }
    }
  }
}

    Thay thế nội dung sau:

    • OAUTH_CLIENT_ID: Mã ứng dụng khách mà bạn đã tạo.
    • OAUTH_CLIENT_SECRET: Khoá bí mật của ứng dụng khách mà bạn đã tạo.

  4. Tiết kiệm mcp_config.json.

  5. Xác thực máy chủ MCP. Bạn có thể xác thực bằng cách sử dụng chế độ cài đặt GUI hoặc CLI:

    • Đối với Antigravity IDE hoặc GUI (Antigravity 2.0):

      1. Mở màn hình cài đặt (ví dụ: nhấp vào Cài đặt ở dưới cùng bên trái hoặc mở Cài đặt người dùng Antigravity).
      2. Chuyển đến phần Tuỳ chỉnh.
      3. Trong mục Installed MCP Servers (Máy chủ MCP đã cài đặt), hãy nhấp vào Refresh (Làm mới).
      4. Tìm gmail trong danh sách, nhấp vào Xác thực, đăng nhập vào Tài khoản Google của bạn, sao chép mã uỷ quyền, dán mã đó vào hộp thoại nhập rồi nhấp vào Gửi.

    • Đối với Antigravity CLI:

      1. Bắt đầu sử dụng Antigravity CLI:

        agy

      2. Mở bảng điều khiển quản lý MCP tương tác bằng cách chạy:

        /mcp

      3. Sử dụng các phím mũi tên để chọn gmail, chuyển đến thao tác Xác thực rồi nhấn phím Enter. Hoàn tất quy trình đăng nhập trong trình duyệt, sao chép mã uỷ quyền, dán mã đó vào lời nhắc của thiết bị đầu cuối rồi nhấn phím Enter.

  6. Xác minh rằng máy chủ được định cấu hình chính xác và đang chạy:

    • Đối với Antigravity IDE hoặc GUI: Nút Đăng xuất sẽ xuất hiện bên cạnh máy chủ trong phần Tuỳ chỉnh > Máy chủ MCP đã cài đặt.
    • Đối với Antigravity CLI: Mở bảng điều khiển /mcp để xem các máy chủ MCP đã định cấu hình. Các máy chủ đã được xác minh và xác thực sẽ hiển thị trạng thái Authed (Đã xác thực) bên cạnh tên của chúng trong bảng điều khiển TUI tương tác. Bạn có thể chọn bất kỳ máy chủ nào trong chế độ xem trang tổng quan để kiểm tra trạng thái và liệt kê tất cả công cụ có sẵn của máy chủ đó.

Máy chủ MCP từ xa đã sẵn sàng để sử dụng trong Antigravity.

Claude

Để sử dụng máy chủ MCP từ xa của Gmail với Claude.ai hoặc Claude Desktop, bạn phải có gói Claude Enterprise, Pro, Max hoặc Team.

Để thêm máy chủ MCP từ xa của Gmail vào Claude, hãy định cấu hình một trình kết nối tuỳ chỉnh bằng mã ứng dụng khách OAuth và khoá bí mật.

  1. Tạo mã ứng dụng khách và khoá bí mật OAuth 2.0:

    1. Trong Google Cloud Console, hãy chuyển đến Google Auth Platform (Nền tảng xác thực của Google) > Clients (Ứng dụng khách) > Create Client (Tạo ứng dụng khách).

      Chuyển đến phần Tạo ứng dụng

    2. Chọn Ứng dụng web làm loại ứng dụng.

    3. Nhập Tên.

    4. Trong mục URI chuyển hướng được uỷ quyền, hãy nhấp vào + Thêm URI, rồi thêm https://claude.ai/api/mcp/auth_callback vào trường URI.

    5. Chọn Sử dụng khách hàng này cho một tác nhân dựa trên AI.

    6. Nhấp vào Tạo rồi sao chép Mã ứng dụng khách và Khoá bí mật của ứng dụng khách.

  2. Định cấu hình máy chủ MCP trong Claude:

    1. Trong Claude.ai hoặc Claude Desktop, hãy chuyển đến phần Cài đặt > Trình kết nối hoặc Cài đặt quản trị > Trình kết nối.
    2. Nhấp vào Thêm trình kết nối tuỳ chỉnh.
    3. Nhập thông tin chi tiết về kết nối cho sản phẩm Gmail:
      • Tên máy chủ: Gmail.
      • URL của máy chủ MCP từ xa: https://gmailmcp.googleapis.com/mcp/v1
    4. Trong phần Cài đặt nâng cao, hãy nhập Mã ứng dụng khách OAuth và Khoá bí mật của ứng dụng khách OAuth.
    5. Nhấp vào Thêm.

Khác

Nhiều ứng dụng AI có cách kết nối với máy chủ MCP từ xa. Thông thường, bạn cần nhập thông tin chi tiết về máy chủ, chẳng hạn như tên, điểm cuối, giao thức truyền tải và phương pháp xác thực. Đối với máy chủ MCP từ xa của Gmail, hãy nhập thông tin sau:

Để biết thêm thông tin chi tiết về cách kết nối các loại ứng dụng khác nhau, hãy xem bài viết Định cấu hình MCP trong ứng dụng AI.

Kiểm thử máy chủ MCP cho Gmail

Sau khi định cấu hình ứng dụng MCP, bạn có thể xác minh kết nối bằng cách chạy một số câu lệnh kiểm thử.

Hãy thử hỏi ứng dụng MCP của bạn những câu hỏi sau:

  • "Ariel đã nói gì trong email gần đây nhất về kế hoạch tiếp thị của chúng ta?"

    Ứng dụng khách lọc email của Ariel bằng gmail.search_threads, truy xuất nội dung của chuỗi thư mới nhất bằng gmail.get_thread, sau đó tóm tắt nội dung đó cho bạn.

  • "Soạn email gửi đến ariel@example.com để thông báo rằng tôi phê duyệt kế hoạch tiếp thị."

    Ứng dụng này sử dụng gmail.create_draft để tạo email trong thư mục thư nháp của bạn, giúp bạn xem lại và gửi email đó từ Gmail.

Nếu các công cụ thực thi thành công và bạn nhận được phản hồi có liên quan, thì máy chủ MCP của Gmail đã được định cấu hình chính xác.

Khắc phục sự cố

Hãy tham khảo các phần sau để giải quyết các vấn đề thường gặp về việc xác thực và kết nối với máy chủ MCP của Gmail.

Kiểm tra sự kiện trong nhật ký OAuth

Nếu bạn gặp vấn đề khi kết nối với máy chủ MCP, hãy kiểm tra lỗi trong nhật ký OAuth. Hãy yêu cầu quản trị viên Google Workspace xem xét sự kiện trong nhật ký OAuth trong công cụ điều tra bảo mật.

Yêu cầu bị từ chối từ ứng dụng OAuth do người dùng uỷ quyền

Nếu các yêu cầu của bạn đến máy chủ MCP bị từ chối, hãy xác minh rằng mã ứng dụng khách OAuth 2.0 do người dùng uỷ quyền cho quy trình OAuth 3 bên của bạn đã chọn Sử dụng ứng dụng này cho tác nhân dựa trên AI trong Nền tảng xác thực của Google > Ứng dụng:

  • Ứng dụng hiện có hỗ trợ chế độ cài đặt này: Chọn Sử dụng ứng dụng này cho một tác nhân dựa trên AI trên ứng dụng OAuth hiện có của bạn.
  • Không thể cập nhật ứng dụng hiện có: Tạo một ứng dụng OAuth mới, chọn Sử dụng ứng dụng này cho tác nhân dựa trên AI rồi cập nhật ứng dụng của bạn để sử dụng ứng dụng đó.
  • Ứng dụng khách hiện tại cũng hỗ trợ các tính năng không phải tác nhân: Tạo một ứng dụng OAuth riêng cho tác nhân AI và giữ lại ứng dụng khách hiện tại cho các tính năng không phải tác nhân.

Để biết hướng dẫn, hãy xem phần Định cấu hình ứng dụng MCP và Quản lý ứng dụng OAuth.

Tài khoản dịch vụ có quyền uỷ quyền trên toàn miền

Nếu ứng dụng của bạn sử dụng tài khoản dịch vụ có tính năng uỷ quyền trên toàn miền cho OAuth 2 chân, thì bạn không thể chọn Sử dụng ứng dụng này cho tác nhân dựa trên AI vì tài khoản dịch vụ không được quản lý trong Google Auth Platform > Ứng dụng:

  • Kiểm soát quyền truy cập: Các yêu cầu gửi đến máy chủ MCP từ những tài khoản dịch vụ này không bị từ chối do thiếu chế độ cài đặt tác nhân. Thay vào đó, quyền truy cập được quản lý bằng chế độ cài đặt uỷ quyền trên toàn miền do quản trị viên Google Workspace quản lý. Để biết thông tin chi tiết về chế độ cài đặt của quản trị viên, hãy xem bài viết Kiểm soát quyền truy cập API bằng tính năng uỷ quyền trên toàn miền.
  • Hành động nhạy cảm: Máy chủ MCP của Google Workspace vẫn trả về lời nhắc lấy thông tin biểu mẫu để xác nhận có sự can thiệp của con người nằm trong quy trình đối với các lệnh gọi công cụ nhạy cảm được thực hiện thông qua tính năng mạo danh người dùng uỷ quyền trên toàn miền.

Yêu cầu từ Apps Script

Nếu gọi máy chủ MCP từ Apps Script, bạn không thể chọn Sử dụng ứng dụng này cho tác nhân dựa trên AI trên ứng dụng OAuth mặc định mà Apps Script tạo và quản lý cho tập lệnh của bạn. Điều này áp dụng ngay cả khi tập lệnh của bạn sử dụng một dự án Google Cloud tiêu chuẩn.

Để gọi máy chủ MCP từ Apps Script, hãy làm như sau:

  1. Trong Google Cloud Console, hãy chuyển đến Nền tảng xác thực của Google > Ứng dụng, tạo một ứng dụng OAuth, rồi chọn Sử dụng ứng dụng này cho một tác nhân dựa trên AI.
  2. Trong tập lệnh, hãy sử dụng thư viện OAuth2 cho Apps Script để uỷ quyền cho người dùng bằng ứng dụng OAuth đó.
  3. Khi bạn gọi máy chủ MCP, hãy gửi mã truy cập mà thư viện trả về thay vì mã thông báo từ ScriptApp.getOAuthToken.

Các dự án Apps Script không gọi máy chủ MCP của Google Workspace sẽ không bị ảnh hưởng.

Lời nhắc đăng nhập lặp lại hằng giờ

Nếu bạn được nhắc đăng nhập lại sau mỗi giờ, thì tức là ứng dụng MCP của bạn không nhận được mã làm mới. Máy chủ OAuth 2.0 của Google chỉ cấp mã làm mới khi yêu cầu uỷ quyền có chứa access_type=offline. Nếu chỉ yêu cầu phạm vi offline_access của OpenID Connect (OIDC), thì bạn sẽ không nhận được mã thông báo làm mới.

Kiểm tra xem ứng dụng MCP của bạn có hỗ trợ các tham số uỷ quyền tuỳ chỉnh hay không:

  • Ứng dụng khách hỗ trợ các tham số uỷ quyền tuỳ chỉnh: Thêm access_type=offline vào yêu cầu uỷ quyền. Để nhận mã làm mới mới cho người dùng đã cấp quyền truy cập, hãy thêm prompt=consent.
  • Ứng dụng không hỗ trợ các tham số uỷ quyền tuỳ chỉnh: Đăng nhập lại mỗi khi mã truy cập hết hạn.

Để biết thông tin chi tiết, hãy xem phần Làm mới mã truy cập.

Tài liệu tham khảo về công cụ

Các công cụ sau đây có sẵn cho máy chủ MCP của Gmail:

  • create_draft
  • get_thread
  • label_message
  • label_thread
  • list_drafts
  • list_labels
  • search_threads
  • unlabel_message
  • unlabel_thread

Lưu ý quan trọng về bảo mật: Tiêm câu lệnh gián tiếp

Khi bạn cho mô hình ngôn ngữ tiếp xúc với dữ liệu không đáng tin cậy, có nguy cơ xảy ra cuộc tấn công chèn câu lệnh gián tiếp. Vì các máy chủ lưu trữ MCP như Google Antigravity có quyền truy cập vào các công cụ và API mạnh mẽ thông qua máy chủ MCP của Gmail, nên họ có thể đọc, sửa đổi và xoá dữ liệu trong Tài khoản Google của bạn.

Để giảm thiểu những rủi ro này, bạn phải sàng lọc câu lệnh và câu trả lời để phát hiện nội dung độc hại hoặc các cuộc tấn công chèn câu lệnh. Bạn có thể sử dụng Model Armor do Google cung cấp hoặc bạn có thể sử dụng giải pháp của riêng mình nếu bạn ghi lại giải pháp đó để người dùng chấp nhận rủi ro đó. Để biết thêm thông tin, hãy xem bài viết Định cấu hình bảo mật cho máy chủ MCP của Google Workspace.

Hãy làm theo các phương pháp hay nhất sau đây:

  • Chỉ sử dụng các công cụ đáng tin cậy. Tuyệt đối không kết nối máy chủ MCP của Gmail với các ứng dụng không đáng tin cậy hoặc chưa được xác minh.
  • Hãy thận trọng với dữ liệu đầu vào không đáng tin cậy. Tránh yêu cầu ứng dụng MCP xử lý email hoặc các tài nguyên khác từ các nguồn chưa được xác minh. Những thông tin đầu vào này có thể chứa các chỉ dẫn ẩn có thể chiếm đoạt phiên của bạn, cho phép kẻ tấn công sửa đổi, đánh cắp hoặc xoá dữ liệu của bạn.
  • Xem tất cả hành động. Hãy luôn xem xét kỹ các hành động mà ứng dụng AI thực hiện thay mặt bạn để đảm bảo các hành động đó là chính xác và phù hợp với ý định của bạn.