Claude Code coi MCP server là công dân hạng nhất, dùng chung được cả trong session CLI và trong panel chat của extension VS Code — tức là bạn cấu hình một lần, dùng ở cả hai nơi. Với Google Sheets, điều này biến terminal bạn đang chạy build/test thành nơi bạn cũng có thể vừa gõ "tổng hợp doanh thu tháng này từ sheet X" vừa nhận kết quả ghi thẳng vào tab mới, không cần mở trình duyệt Google Sheets. Bài này đi từng bước từ cài đặt server, đọc range để phân tích, ghi kết quả trở lại, đến kỹ thuật viết prompt để tránh agent đọc sai range hay hiểu nhầm tiêu đề cột.
Cài Đặt và Kết Nối Google Sheets MCP với Claude Code
Trước tiên, chọn server implementation. Vì không có server chính thức duy nhất do Google hay Anthropic duy trì (xem lại bài 1 nếu bạn chưa đọc), bài này dùng server Python cộng đồng phổ biến mcp-google-sheets — chạy qua stdio, hỗ trợ cả OAuth và service account, và có tool surface rõ ràng (read_range, write_range, list_sheets, add_sheet, create_spreadsheet).
uvx --from mcp-google-sheets mcp-google-sheets --help
pip install mcp-google-sheets
Tạo service account trong Google Cloud Console (APIs & Services → Credentials → Create Credentials → Service account), bật Google Sheets API và Google Drive API cho project, tải file JSON key về, sau đó share từng spreadsheet cần dùng với email service account (dạng agent-sheets@your-project.iam.gserviceaccount.com) như share với một người dùng thật.
Claude Code đọc cấu hình MCP server từ .mcp.json ở root repo (project scope) hoặc từ config user-level cho server bạn muốn dùng ở mọi project. Thêm server bằng CLI thay vì tự sửa tay JSON — nó validate entry và ghi giúp bạn:
claude mcp add sheets --scope user -- \
uvx --from mcp-google-sheets mcp-google-sheets
Sau đó set env var cần thiết trong .mcp.json, hoặc export ngay trong shell trước khi chạy claude mcp add:
{
"mcpServers": {
"sheets": {
"command": "uvx",
"args": ["--from", "mcp-google-sheets", "mcp-google-sheets"],
"env": {
"SERVICE_ACCOUNT_PATH": "/Users/you/.config/sheets-mcp/service-account.json"
}
}
}
}
Nếu commit .mcp.json vào repo, đừng hardcode đường dẫn tuyệt đối tới máy cá nhân — dùng biến môi trường tham chiếu (${SHEETS_SA_PATH}) và mỗi máy tự set giá trị riêng trong shell profile:
claude mcp get sheets
Extension VS Code tự đọc cùng file .mcp.json này ngay khi bạn mở repo — không cần bước cấu hình riêng. Mở panel Claude Code, và tool Sheets sẽ xuất hiện trong danh sách tool-approval ngay lần đầu agent gọi thử. Nên approve từng tool cụ thể (sheets_write_range) thay vì approve tất cả — bạn muốn được hỏi mỗi lần ghi cho đến khi tin tưởng workflow.
Mẹo: Chạy thử chính xác command trong
argscủa.mcp.jsontrực tiếp ở terminal trước khi tin vào Claude Code — nó tách được lỗi "config parse sai" ra khỏi lỗi "server thực sự start lỗi", hai loại lỗi nhìn giống nhau trong log Claude Code nhưng cách sửa hoàn toàn khác.
Đọc Range và Tạo Phân Tích Từ Dữ Liệu Spreadsheet
Khi server đã connect (claude mcp list hiện sheets: connected), workflow đọc-phân-tích cơ bản chỉ cần một câu prompt rõ ràng về phạm vi và mục tiêu:
Đọc range "Orders!A1:H2000" trong spreadsheet có ID 1AbCxyz...
Dòng đầu là tiêu đề cột. Tính tổng cột "amount" theo từng giá trị unique của cột "region",
chỉ tính các dòng có cột "status" = "completed".
In kết quả dạng bảng ra đây, chưa cần ghi lại vào sheet.
Điều quan trọng nhất ở bước này: agent cần ID spreadsheet (chuỗi trong URL giữa /d/ và /edit), không phải tên file — tên file trùng nhau rất phổ biến (nhiều người đặt tên "Copy of Q3 Report" giống nhau), và một số server tìm theo tên qua Drive API sẽ trả nhầm file nếu có nhiều kết quả khớp.
Với dữ liệu lớn (>10.000 dòng), đừng để agent đọc toàn bộ sheet vào context window (cửa sổ ngữ cảnh) cùng lúc — vừa tốn token, vừa dễ bị cắt giữa đường. Yêu cầu agent đọc theo batch, hoặc — tốt hơn — để agent viết một đoạn script Python ngắn dùng chính thư viện gspread hoặc google-api-python-client để xử lý phía server, chỉ trả về kết quả tổng hợp cuối cùng vào context.
Dữ liệu ở Orders có khoảng 15.000 dòng. Đừng đọc toàn bộ vào context.
Viết và chạy một script Python dùng service account credentials tại
$SHEETS_SA_PATH để tính tổng theo region trực tiếp, chỉ show cho tôi
bảng kết quả tổng hợp (dự kiến dưới 20 dòng).
Mẹo: Với sheet lớn, luôn yêu cầu agent ước lượng số dòng/số token trước khi đọc toàn bộ range — một câu hỏi "sheet này có khoảng bao nhiêu dòng?" trước khi ra lệnh phân tích giúp bạn quyết định giữa đọc trực tiếp hay để agent viết script xử lý phía ngoài.
Ghi Kết Quả, Tóm Tắt, và Các Cột Sinh Ra Trở Lại Sheet
Sau khi có kết quả phân tích, bước ghi lại cần cẩn trọng hơn bước đọc vì nó có tác dụng phụ thật. Pattern an toàn nhất: luôn ghi vào tab mới, không ghi đè tab nguồn.
Tạo tab mới tên "Region-Summary" trong spreadsheet 1AbCxyz...
Ghi bảng tổng hợp vừa tính vào tab đó, bắt đầu từ ô A1, dòng đầu là tiêu đề
("Region", "Total Amount", "Order Count"). Dùng valueInputOption USER_ENTERED
để Sheets tự format số tiền đúng kiểu.
Với việc sinh cột mới trên chính tab dữ liệu gốc (ví dụ thêm cột "Sentiment" từ phân tích văn bản feedback khách hàng), rủi ro lớn nhất là lệch dòng — agent ghi giá trị cột G ứng với dòng đọc được ở thời điểm đọc, nhưng nếu có người khác đang chỉnh sheet đồng thời (thêm/xóa dòng), thứ tự dòng lúc ghi có thể khác lúc đọc.
Trước khi ghi cột "Sentiment" (cột I) vào tab Feedback, đọc lại cột A (ID phản hồi)
một lần nữa ngay trước khi ghi, để xác nhận số dòng và ID khớp với lúc bạn đọc dữ liệu
ban đầu. Nếu số dòng thay đổi, dừng lại và báo cho tôi biết trước khi ghi.
Mẹo: Với mọi lệnh ghi cột phụ thuộc vào thứ tự dòng (không phải ghi theo key/ID rõ ràng), luôn yêu cầu agent đọc lại cột khóa ngay trước khi ghi để phát hiện lệch dòng do người khác chỉnh sheet đồng thời — đây là lỗi âm thầm khó phát hiện nhất trong toàn bộ workflow Sheets MCP.
Kỹ Thuật Viết Prompt Để Xử Lý Range và Header Ổn Định
Ba lỗi prompt phổ biến nhất khi làm việc với Sheets MCP qua Claude Code, và cách tránh:
1. Không chỉ rõ dòng tiêu đề nằm ở đâu. Nếu sheet có 2 dòng tiêu đề (dòng mô tả + dòng tên cột thật), agent thường mặc định dòng 1 là header — dẫn đến lệch toàn bộ mapping tên cột.
Sai: "Đọc dữ liệu từ Orders và tính tổng theo region."
Đúng: "Đọc Orders!A3:H2000 — dòng 1-2 là metadata, dòng 3 là header thật
(amount, region, status...), dữ liệu bắt đầu từ dòng 4."
2. Range không có giới hạn dòng rõ ràng. Orders!A:H (không giới hạn dòng cuối) khiến một số server đọc đến hết những dòng có dữ liệu, nhưng một số khác trả lỗi hoặc timeout trên sheet lớn có nhiều dòng trống rải rác. Luôn chỉ rõ dòng cuối cụ thể, hoặc yêu cầu agent trước tiên gọi tool lấy sheet metadata để biết chính xác rowCount.
3. Không phân biệt "sheet" và "spreadsheet". Trong tiếng Việt cả hai đôi khi bị gọi lẫn là "file Excel" hay "bảng tính" — nhưng với Google Sheets API, một spreadsheet (file) chứa nhiều sheet (tab). Prompt mơ hồ như "sheet Q3 report" có thể nghĩa là cả file hoặc chỉ một tab, gây agent chọn nhầm đối tượng.
Chuẩn xác: "Trong spreadsheet ID 1AbCxyz... (tên file 'Q3-Report'),
đọc tab (sheet) có tên 'Raw-Data'."
Mẹo: Xây một "cheat sheet" ngắn cho chính project của bạn — liệt kê ID spreadsheet, tên các tab, và vị trí dòng header thật của từng tab hay dùng — dán nó vào file rule của agent (
CLAUDE.mdhoặc tương đương). Việc này loại bỏ gần hết lỗi mơ hồ về range/header trong các session sau.
Tips
- Luôn dùng ID spreadsheet, không dùng tên file, khi ra lệnh cho agent — tránh nhầm giữa các file trùng tên.
- Với sheet lớn, ưu tiên để agent xử lý bằng script phía server, chỉ trả kết quả tổng hợp vào context window.
- Đọc lại cột khóa ngay trước khi ghi cột phụ thuộc thứ tự dòng, để phát hiện lệch dòng do chỉnh sửa đồng thời.
- Ghi rõ vị trí dòng header thật trong mọi prompt liên quan đến range có cấu trúc header không chuẩn.
Mẹo: Bật approval thủ công cho riêng tool ghi (
write_range,batch_update) trong Claude Code ngay cả sau khi bạn đã tin tưởng workflow đọc — tách rời mức độ tin cậy giữa "đọc" và "ghi" là thói quen tốt nhất để tránh sự cố ngoài ý muốn trên dữ liệu sản xuất.