@lmdat/google-sheets-oauth-mcp

Local MCP server (Node.js + TypeScript) đọc/ghi/tạo Google Sheets, kèm tạo chart, thông qua OAuth — server hoạt động đại diện chính tài khoản Google đang đăng nhập, không cần share thủ công từng file như cách dùng Service Account.

Yêu cầu

• Node.js 18+
• Tài khoản Google (cá nhân hoặc Workspace)
• 1 project trên Google Cloud Console

1. Setup Google Cloud Console

1. Vào console.cloud.google.com, tạo hoặc chọn 1 project.
2. APIs & Services → Library → enable Google Sheets API và Google Drive API.
3. APIs & Services → OAuth consent screen:
   • User type: chọn External (tài khoản Gmail cá nhân chỉ có lựa chọn này; Internal chỉ dành cho tài khoản Google Workspace).
   • Điền App name và support email (giá trị tùy ý, không ảnh hưởng chức năng).
   • Sau khi tạo, vào tab Audience → bấm Publish App → Confirm. Bước này nên làm ngay từ đầu — nếu bỏ qua, app ở trạng thái Testing và refresh token sẽ tự hết hạn sau 7 ngày.
4. APIs & Services → Credentials → Create Credentials → OAuth client ID:
   • Application type: Desktop app (không chọn Web application).
   • Lưu lại Client ID và Client secret hiện ra sau khi tạo.

2. Cài đặt

npm install

3. Build

| Lệnh | Output | Dùng khi nào | | --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------- | | npm run build | build/index.js + build/auth.js | Phát triển/debug, code dễ đọc | | npm run build:min | dist/index.js (1 file, đã gộp + minify) | Dùng để chạy thật / publish | | npm run build:obfuscate | dist/index.js (đã obfuscate) | Muốn code khó đọc hơn khi chia sẻ (không phải mã hóa, chỉ gây khó đọc) |

Build tối thiểu 1 lần trước khi cấu hình opencode ở bước tiếp theo.

4. Cấu hình credential

export GOOGLE_OAUTH_CLIENT_ID="xxx.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="GOCSPX-xxx"

Hoặc khai báo trực tiếp trong config opencode ở bước 5 (mục environment), không cần export ra shell.

Biến môi trường optional:

| Var | Default | Khi nào cần đổi | | ------------------------------ | ------------------------ | ------------------------------------------- | | GOOGLE_OAUTH_REDIRECT_PORT | 53682 | Port bị chương trình khác chiếm dụng | | MCP_GSHEETS_TOKEN_DIR | ~/.mcp-google-sheets | Muốn lưu file token ở vị trí khác |

5. Cấu hình trong opencode

Có 2 cách trỏ tới MCP server, chọn 1 trong 2.

Cách 1 — Trỏ trực tiếp đến file (đơn giản, không cần publish)

"google-sheets": {
  "type": "local",
  "command": [
    "node",
    "/duong-dan-tuyet-doi/google-sheets-oauth-mcp/dist/index.js"
  ],
  "enabled": true,
  "environment": {
    "GOOGLE_OAUTH_CLIENT_ID": "xxx.apps.googleusercontent.com",
    "GOOGLE_OAUTH_CLIENT_SECRET": "GOCSPX-xxx"
  }
}

Thay /duong-dan-tuyet-doi/... bằng đường dẫn thật trên máy đang chạy opencode. Phù hợp khi chỉ dùng trên 1 máy, không cần chia sẻ cho người khác.

Cách 2 — Dùng qua npm package (cần publish trước)

Nếu package đã được publish lên npm registry (xem mục 8), cấu hình gọn hơn, không cần biết đường dẫn cụ thể trên máy:

"google-sheets": {
  "type": "local",
  "command": [
    "npx",
    "-y",
    "@lmdat/google-sheets-oauth-mcp@latest"
  ],
  "enabled": true,
  "environment": {
    "GOOGLE_OAUTH_CLIENT_ID": "xxx.apps.googleusercontent.com",
    "GOOGLE_OAUTH_CLIENT_SECRET": "GOCSPX-xxx"
  }
}

6. Lần đầu sử dụng — cần đăng nhập 1 lần

Khi opencode gọi tool đầu tiên (ví dụ drive_list_spreadsheets), server sẽ:

1. Tự mở browser (hoặc in URL ra log nếu máy không tự mở được trình duyệt — copy URL đó dán vào browser thủ công).
2. Đăng nhập Google và bấm Allow.
3. Browser hiện thông báo đăng nhập thành công → token được lưu vào ~/.mcp-google-sheets/token.json.

Từ lần sau không cần đăng nhập lại — token tự refresh ngầm.

Flow này cần trình duyệt trên cùng máy đang chạy MCP server, vì server mở 1 HTTP server tạm trên 127.0.0.1 để nhận redirect từ Google. Nếu server được chạy trên môi trường không có giao diện (ví dụ VPS headless), flow này sẽ không hoạt động và cần cách xác thực khác.

7. Đổi scope sau này → phải đăng nhập lại

Nếu chỉnh sửa danh sách scope trong src/auth.ts, cần xóa file token cũ (~/.mcp-google-sheets/token.json) rồi chạy lại để đăng nhập lại. Google gắn cố định scope vào thời điểm cấp quyền — token cũ không tự nhận thêm quyền mới.

8. (Tùy chọn) Publish lên npm để dùng theo Cách 2

npm login                       # nếu chưa đăng nhập npm
npm run build:min
npm publish --access public     # bắt buộc thêm flag này nếu dùng scoped package (@username/...)

Kiểm tra trước khi publish thật:

npm run build:min && npm pack --dry-run

9. Danh sách tool

| Tool | Chức năng | | ----------------------------------- | ------------------------------------------------------------------------------- | | drive_list_spreadsheets | Tìm sheet theo tên (Drive API), không cần biết ID trước | | sheets_create | Tạo sheet mới, tùy chọn đặt vào folder cụ thể và tạo sẵn nhiều tab | | sheets_read | Đọc 1 range, trả về mảng 2 chiều | | sheets_write | Ghi đè giá trị trong 1 range | | sheets_append | Thêm hàng vào cuối bảng dữ liệu hiện có | | sheets_clear | Xóa giá trị trong 1 range (giữ nguyên format) | | sheets_list_tabs | Liệt kê tên các tab trong file | | sheets_create_chart | Tạo chart COLUMN/BAR/LINE/AREA/SCATTER/PIE từ dữ liệu có sẵn | | sheets_create_candlestick_chart | Tạo chart nến (OHLC) cho dữ liệu giá | | sheets_write_json | Ghi dữ liệu JSON vào Google Sheet | | sheets_append_json | Tự động append dữ liệu JSON vào Google Sheet (tự tạo file/tab nếu chưa có) |

Mọi tool đọc/ghi (trừ drive_list_spreadsheets và sheets_create) đều cần spreadsheet_id — lấy từ URL của sheet hoặc dùng drive_list_spreadsheets để tìm theo tên.

Lưu ý khi dùng 2 tool tạo chart

• Mọi range truyền vào phải ghi đủ tên sheet, theo dạng "TenSheet!A2:E50". Range thiếu tên sheet không được hỗ trợ.
• sheets_create_candlestick_chart yêu cầu data_range có đúng 5 cột liên tiếp, theo thứ tự cố định: Date, Open, High, Low, Close — đúng convention chuẩn của Google Sheets khi chọn data bằng tay qua Insert > Chart. Sai thứ tự cột (ví dụ đảo Open/Close) không gây ra lỗi — chart vẫn được tạo nhưng màu nến hiển thị ngược nghĩa, cần tự kiểm tra bằng mắt sau khi tạo.
• anchor_cell (vị trí đặt chart) là optional ở cả 2 tool — nếu không truyền, chart tự đặt ngay bên phải vùng dữ liệu nguồn.

10. Scope OAuth đang sử dụng

const SCOPES = [
  "https://www.googleapis.com/auth/spreadsheets",    // đọc/ghi/tạo sheet
  "https://www.googleapis.com/auth/drive.readonly",  // tìm/list toàn bộ sheet user có quyền
  "https://www.googleapis.com/auth/drive.file",       // move file mới tạo vào folder
];

drive.file chỉ cho phép truy cập file do chính app này tạo ra (hoặc do user chọn qua Picker) — không đủ để di chuyển hay sửa file cũ không phải do app tạo. Vì vậy cần thêm drive.readonly riêng cho việc tìm/list sheet có sẵn. Scope drive (toàn quyền) không được sử dụng vì rộng hơn mức cần thiết.

11. Ví dụ câu lệnh trong opencode

Tìm sheet có chữ "Ngân sách"
Tạo sheet mới tên "Theo dõi cổ phiếu 2026" với 2 tab: Giao dịch, Tổng hợp
Đọc A1:E20 trong tab Giao dịch của sheet [tên/id vừa tạo]
Append 1 hàng vào tab Giao dịch: 2026-06-25, VNM, Buy, 1000, 42500
Tạo candlestick chart "Giá VNM Q2 2026" từ range Data!A2:E50

12. So sánh với bản dùng Service Account

| | Service Account | OAuth (bản này) | | ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------- | | Truy cập sheet có sẵn | Phải share thủ công email service account | Tự thấy mọi sheet user đã có quyền | | Tìm sheet theo tên | Không hỗ trợ | Có, quadrive_list_spreadsheets | | File mới tạo | Thuộc Drive của service account | Thuộc Drive của chính user | | Setup ban đầu | Nhanh, không cần đăng nhập trình duyệt | Cần đăng nhập trình duyệt 1 lần, cấu hình OAuth consent screen | | Phù hợp | Vài sheet cố định, biết trước ID | Cần linh hoạt nhiều sheet, tạo/tìm theo tên |