Google Drive MCP Setup: Cursor | AgenticSkillset.org

Cursor là IDE fork từ VS Code với Agent Mode tích hợp sẵn, hỗ trợ MCP (Model Context Protocol) qua file .cursor/mcp.json. Khi gắn Google Drive MCP vào Cursor, bạn có thể kéo business spec nằm trên Drive thẳng vào ngữ cảnh code đang mở, mà không cần chuyển qua chuyển lại giữa browser và editor — một trong những workflow tiết kiệm thời gian rõ rệt nhất khi bạn đang implement một tính năng dựa trên tài liệu do product team viết. Bài này hướng dẫn kết nối cụ thể, cách đưa spec vào code context, cách sinh scaffold triển khai từ tài liệu Drive, và những hạn chế thực tế bạn cần biết khi dùng Cursor cho việc này.

Kết Nối Google Drive MCP Vào Cursor Agent Mode

Cursor đọc cấu hình MCP server từ .cursor/mcp.json (project-scoped, ưu tiên khi làm việc theo team) hoặc ~/.cursor/mcp.json (global, áp dụng cho mọi project trên máy bạn). Trước khi cấu hình, tạo OAuth Client ID loại "Desktop app" trong Google Cloud Console và bật Google Drive API.

{
  "mcpServers": {
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@isaacphi/mcp-gdrive"],
      "env": {
        "CLIENT_ID": "${GDRIVE_OAUTH_CLIENT_ID}",
        "CLIENT_SECRET": "${GDRIVE_OAUTH_CLIENT_SECRET}",
        "GDRIVE_CREDS_DIR": "${HOME}/.config/gdrive-mcp"
      }
    }
  }
}

Set biến môi trường tương ứng trong shell profile trước khi mở Cursor (Cursor kế thừa environment của tiến trình khởi động nó, nên nếu bạn set biến sau khi Cursor đã chạy, cần restart lại app để nhận biến mới):

export GDRIVE_OAUTH_CLIENT_ID="1234567890-abc.apps.googleusercontent.com"
export GDRIVE_OAUTH_CLIENT_SECRET="GOCSPX-xxxxxxxxxxxxxxxxxxxx"

Vào Cursor Settings → MCP để xem trạng thái server: cần thấy dấu chấm xanh cạnh gdrive kèm số lượng tool đã load (thường 3, gồm gdrive_search, gdrive_read_file, gdrive_list_files). Nếu dấu chấm đỏ, click vào tên server để xem log lỗi trực tiếp trong panel — cách debug nhanh hơn nhiều so với việc lục log file thủ công.

Lần đầu Agent Mode gọi một tool gdrive_*, một tab browser sẽ tự mở để bạn đăng nhập Google và cấp quyền theo scope đã cấu hình. Sau khi đồng ý, quay lại Cursor và tool call sẽ tiếp tục chạy — token cache lưu trong GDRIVE_CREDS_DIR, không cần đăng nhập lại ở các phiên sau.

Để dùng tool trong Agent Mode, mở Composer (Cmd/Ctrl + I), gõ @ để xem danh sách MCP tool khả dụng, hoặc đơn giản là ra yêu cầu bằng ngôn ngữ tự nhiên — Cursor tự chọn tool phù hợp:

Tìm trên Google Drive file PRD nào có liên quan tới tính năng
"saved search" mà tôi đang implement trong branch hiện tại.

Mẹo: Nếu server hiện dấu chấm đỏ ngay sau khi thêm config, việc đầu tiên cần kiểm tra là bạn đã bật Google Drive API trong đúng project Cloud Console tương ứng với OAuth Client ID hay chưa — đây là lỗi phổ biến nhất khi mới setup, vì Cloud Console cho phép tạo OAuth Client ID trước khi bật API tương ứng, dẫn đến lỗi runtime khó hiểu (accessNotConfigured) chứ không báo lỗi ngay lúc cấu hình.

Đưa Business Spec Vào Code Context Trong Cursor

Điểm mạnh lớn nhất của Cursor so với các CLI khác là Agent Mode có thể vừa đọc file code đang mở trong editor, vừa đọc tài liệu trên Drive, trong cùng một lượt suy luận — rất phù hợp khi bạn đang implement mà cần đối chiếu ngược lại spec gốc.

So sánh spec trong file Drive "PRD - Saved Search v2" với code hiện
tại trong src/features/saved-search/. Liệt kê những requirement
trong PRD mà code hiện tại CHƯA implement, và những behavior trong
code mà PRD không hề nhắc tới (có thể là edge case đã được xử lý
ngoài spec, cần confirm có đúng ý định không).

Cursor Agent Mode sẽ đọc PRD qua gdrive_read_file, đọc code qua các tool filesystem sẵn có, và tự đối chiếu — kết quả là một danh sách gap rất cụ thể, thường chính xác hơn việc bạn tự đọc lại spec dài rồi nhớ trong đầu để so với code.

Một pattern khác rất hữu ích khi bạn cần viết code mới dựa trên business rule mô tả trong tài liệu:

Đọc phần "Validation Rules" trong file Drive "Business Rules -
Discount Engine". Implement các rule đó dưới dạng function
validateDiscountEligibility() trong src/discount/validator.ts,
viết kèm unit test cho từng rule (dùng framework test hiện có
trong project).

Vì Cursor có sẵn context về codebase (convention đặt tên, framework test đang dùng, style code hiện tại), code sinh ra từ business rule đọc trên Drive thường khớp convention project tốt hơn so với việc bạn tự paste nội dung business rule vào một chat rời rạc không có context code.

Mẹo: Khi yêu cầu Cursor đối chiếu spec với code, luôn chỉ định rõ đường dẫn thư mục code cụ thể (ví dụ src/features/saved-search/) thay vì để agent tự quét toàn bộ repo — với repo lớn, việc này vừa chậm vừa dễ khiến agent lẫn business logic của feature khác vào kết quả so sánh.

Sinh Scaffold Triển Khai Từ Tài Liệu Drive

Ngoài việc so sánh, Cursor còn có thể dùng tài liệu Drive làm nguồn để sinh scaffold code ban đầu — đặc biệt hữu ích ở giai đoạn bắt đầu implement một tính năng hoàn toàn mới, khi bạn chưa có gì trong repo để agent tham chiếu.

Đọc file Drive "Technical Design - Webhook Delivery Service". Dựa
vào phần "API Contract" trong tài liệu, sinh scaffold cho:
1. Route handler (theo pattern route hiện có trong src/api/routes/)
2. DTO/type định nghĩa request và response
3. File test rỗng với các test case tên tương ứng từng acceptance
   criteria được mô tả trong tài liệu (chưa cần viết assertion,
   chỉ cần it.todo() hoặc tương đương)

Không cần implement logic nghiệp vụ thật, chỉ cần scaffold đúng
cấu trúc để tôi tiếp tục điền vào.

Yêu cầu rõ "chỉ cần scaffold, không implement logic thật" là rất quan trọng ở bước này — nó giữ cho agent tập trung vào việc dựng đúng cấu trúc khớp với convention project và đúng contract được mô tả trong tài liệu, tránh trường hợp agent tự đoán logic nghiệp vụ phức tạp (dễ sai) khi bạn chưa yêu cầu.

Sau khi có scaffold, một prompt tiếp theo hữu ích là yêu cầu agent tự rà soát lại đối chiếu với tài liệu gốc:

Rà lại scaffold vừa tạo, đối chiếu từng field trong DTO với đúng
tên field được nhắc trong tài liệu "API Contract" — nếu có field
nào bạn đặt tên khác với tài liệu (ví dụ do convention camelCase
của project khác với tài liệu), ghi rõ ra để tôi biết đó là chủ
động đổi tên, không phải sai sót.

Mẹo: Luôn tách rõ hai bước — sinh scaffold và implement logic thật — thành hai prompt riêng biệt. Gộp chung một prompt "đọc tài liệu rồi implement luôn toàn bộ" thường ra kết quả kém hơn, vì agent phải cân bằng giữa việc hiểu đúng contract và việc suy luận logic nghiệp vụ phức tạp trong cùng một lượt, dễ sai sót ở cả hai phần.

Hạn Chế Và Cách Khắc Phục Khi Dùng Google Drive MCP Trong Cursor

Agent Mode có thể timeout với file rất lớn. Google Sheets có hàng nghìn dòng, hoặc Slides có trên 50 slide, có thể khiến gdrive_read_file trả về response quá lớn, làm Agent Mode phản hồi chậm hoặc bị cắt giữa chừng. Cách khắc phục: yêu cầu agent chỉ đọc một phần cụ thể trước (ví dụ "chỉ đọc slide 1 đến 20"), hoặc với Sheets, yêu cầu lọc trước theo điều kiện ngay trong prompt để giảm khối lượng dữ liệu cần xử lý.

Không có cơ chế cache nội dung giữa các lượt hỏi trong cùng session. Mỗi lần bạn hỏi lại về cùng một file, Agent Mode có thể gọi lại gdrive_read_file từ đầu thay vì dùng lại nội dung đã đọc trước đó trong context — vừa tốn thời gian, vừa tốn quota API. Nếu bạn biết sẽ hỏi nhiều câu về cùng một tài liệu, gộp các câu hỏi liên quan vào một prompt duy nhất thay vì hỏi rời rạc nhiều lượt.

Không phân biệt rõ version file nếu tên trùng nhau. Nếu Drive có nhiều file cùng tên (rất phổ biến với thói quen "Save As" tạo bản copy), gdrive_search có thể trả về nhiều kết quả trùng tên khiến agent chọn nhầm bản cũ. Luôn yêu cầu agent liệt kê modifiedTime khi có nhiều kết quả trùng tên, và tự bạn xác nhận lại file đúng trước khi cho agent đọc sâu.

OAuth token có thể hết hạn quyền truy cập nếu admin Workspace thay đổi policy. Với tài khoản Google Workspace của công ty, admin có thể thu hồi hoặc thay đổi policy truy cập app bên thứ ba bất kỳ lúc nào, khiến token đang hoạt động bỗng bị từ chối. Khi gặp lỗi xác thực bất ngờ dù trước đó vẫn chạy tốt, việc đầu tiên nên kiểm tra là chính sách OAuth app truy cập của tổ chức, không phải chỉ debug ở phía config MCP.

Mẹo: Với file Sheets/Slides lớn, luôn thu hẹp phạm vi ngay trong prompt đầu tiên (theo range dòng, theo số slide, theo điều kiện lọc) thay vì để agent tự đọc toàn bộ rồi mới lọc — cách này vừa nhanh hơn, vừa tránh được tình trạng response quá lớn làm Agent Mode phản hồi chập chờn.

Mẹo Và Lưu Ý Thực Chiến

Cursor phù hợp nhất cho workflow "đọc spec song song với code đang implement" — nếu bạn chỉ cần tổng hợp tài liệu thuần (không liên quan gì tới code hiện có), một CLI thuần như Claude Code hay Gemini CLI thường nhẹ và nhanh hơn.
Restart Cursor sau mỗi lần đổi biến môi trường liên quan tới OAuth Client — đây là lỗi rất hay gặp khiến người mới nghĩ rằng config sai, trong khi thực chất chỉ là Cursor chưa nạp lại environment mới.
Với team nhiều người dùng Cursor cùng project, mỗi người nên tự đăng nhập OAuth bằng tài khoản Google cá nhân của mình (file .cursor/mcp.json commit chung không chứa token, chỉ chứa Client ID/Secret dạng biến môi trường) — tránh việc cả team vô tình dùng chung một token cache của một người.

Mẹo: Lưu lại trong .cursor/rules hoặc file convention của project một đoạn mô tả ngắn về những shared drive/folder mà agent được phép truy cập, để Agent Mode ưu tiên đúng phạm vi tìm kiếm ngay từ lần hỏi đầu tiên, thay vì phải thử qua nhiều folder không liên quan trước khi tìm đúng tài liệu.