Maru Sheets

MCP server cho phép AI agent đọc/ghi/format Google Sheets qua API v4.

---

👩‍💼 DÀNH CHO NGƯỜI DÙNG

Bạn không cần biết code. Chỉ cần mở Antigravity 2.0 (hoặc AI coding agent khác), paste đoạn prompt bên dưới, rồi làm theo khi AI hỏi.

Paste prompt này vào Antigravity 2.0:

Tôi cần bạn cài đặt MCP server "maru-sheets-mcp" để tôi có thể đọc và ghi Google Sheets từ đây.

Đọc file README.md trong repo https://github.com/leaddaruma-web/maru-sheets-mcp — phần "DÀNH CHO AI CODING AGENT" có hướng dẫn chi tiết từng bước.

Làm hết tất cả các bước giúp tôi — bao gồm cả kiểm tra/cài Node.js nếu máy chưa có.

Hướng dẫn tôi tạo credentials.json trên Google Cloud (theo Bước 2 trong README).

Tôi chỉ cần click "Cho phép" khi trình duyệt mở ra hỏi quyền Gmail.

Bắt đầu.

Sau đó AI sẽ tự làm mọi thứ. Bạn chỉ cần:

• Click "Cho phép" khi trình duyệt mở ra hỏi quyền Gmail (1 lần duy nhất)
• Restart Antigravity sau khi AI báo cấu hình xong (nếu AI yêu cầu)

Sau khi cài xong, bạn có thể bảo AI:

• "Đọc dữ liệu từ Sheet [dán link Sheet] tab Nhật ký, cột A đến K"
• "Ghi danh sách sau vào Sheet [dán link Sheet] bắt đầu từ ô A2: ..."
• "Tạo tab mới tên 'Tháng 7' trong Sheet [dán link Sheet]"
• "Format header: nền xanh đậm, chữ trắng, in đậm"
• "Set công thức tính tổng cột B vào ô B101"

Lưu ý

• Sheet phải được share cho Gmail bạn — nếu AI báo "insufficient permission", mở Sheet đó → click Share → thêm Gmail của bạn (quyền Editor)
• Chỉ cần cài 1 lần — những lần sau mở Antigravity là dùng được luôn

---

🤖 DÀNH CHO AI CODING AGENT

Phần này dành cho AI agent đọc và tự thực hiện. Người dùng không cần đọc phần này.

Bước 0 — Kiểm tra và cài Node.js (nếu chưa có)

node --version

Nếu lệnh trên báo lỗi hoặc version < 18, cài Node.js:

• Windows: tải và chạy installer từ https://nodejs.org/en/download/ (chọn bản LTS, chạy file .msi, chọn tất cả mặc định). Sau khi cài xong cần mở terminal mới để node có trong PATH.
• macOS: brew install node hoặc tải installer từ https://nodejs.org/
• Linux: curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs

Kiểm tra lại sau khi cài:

node --version  # phải >= 18
npm --version   # phải có

Bước 1 — Clone repo

git clone https://github.com/leaddaruma-web/maru-sheets-mcp.git
cd maru-sheets-mcp

Nếu máy chưa có git:

• Windows: tải từ https://git-scm.com/download/win, cài mặc định
• macOS: xcode-select --install
• Linux: sudo apt-get install git

Bước 2 — Tạo file credentials.json

File này chứa thông tin OAuth client — không có trong repo (bảo mật). Người dùng tự tạo trên Google Cloud (miễn phí).

BÁO CHO NGƯỜI DÙNG: "Bạn cần tạo credentials trên Google Cloud — miễn phí, chỉ mất 3 phút. Tôi sẽ hướng dẫn từng bước, bạn chỉ cần click theo."

Hướng dẫn người dùng mở trình duyệt và làm theo:

Bước 2.1. Tạo Google Cloud project:

• Mở https://console.cloud.google.com/
• Đăng nhập bằng Gmail sẽ dùng để đọc/ghi Sheet
• Click menu dropdown project ở thanh trên (cạnh logo Google Cloud) → "New Project"
• Đặt tên project: maru-sheets-mcp → click "Create"
• Đợi vài giây, chọn project vừa tạo từ dropdown

Bước 2.2. Bật Google Sheets API:

• Mở https://console.cloud.google.com/apis/library/sheets.googleapis.com
• Click "Enable" (Bật)
• Mở thêm https://console.cloud.google.com/apis/library/drive.googleapis.com
• Click "Enable" (Bật)

Bước 2.3. Cấu hình OAuth consent screen:

• Mở https://console.cloud.google.com/apis/credentials/consent
• Chọn "External" → click "Create"
• Điền:
  • App name: maru-sheets-mcp
  • User support email: chọn Gmail của bạn
  • Developer contact: nhập Gmail của bạn
• Click "Save and Continue" qua các bước còn lại (Scopes, Test users) → click "Back to Dashboard"
• Ở trang Consent screen, click "Publish App" nếu muốn dùng lâu dài (nếu chỉ test thì bỏ qua)

Bước 2.4. Tạo OAuth Client ID:

• Mở https://console.cloud.google.com/apis/credentials
• Click "+ Create Credentials" → "OAuth client ID"
• Application type: chọn "Desktop app"
• Name: maru-sheets-mcp
• Click "Create"
• MÀN HÌNH HIỆN RA CLIENT ID VÀ CLIENT SECRET — copy cả 2 giá trị này

Bước 2.5. Tạo file credentials.json:

Tạo file credentials.json ở thư mục gốc repo (maru-sheets-mcp/credentials.json) với nội dung:

{
  "installed": {
    "client_id": "THAY_CLIENT_ID_VAO_DAY",
    "project_id": "maru-sheets-mcp",
    "client_secret": "THAY_CLIENT_SECRET_VAO_DAY",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost:4571/oauth2callback"]
  }
}

Thay THAY_CLIENT_ID_VAO_DAY và THAY_CLIENT_SECRET_VAO_DAY bằng giá trị vừa copy ở B4.

BÁO CHO NGƯỜI DÙNG: "Xong bước tạo credentials! Tiếp tục cài đặt nhé."

Bước 3 — Cài dependencies

npm install

Bước 4 — Xác thực Gmail (chỉ 1 lần)

npm run auth

Lệnh này sẽ:

1. Mở trình duyệt tại URL xác thực Google
2. Người dùng đăng nhập Gmail và click "Cho phép" / "Allow"
3. Trình duyệt chuyển hướng về localhost → file token.json được tạo tự động

BÁO CHO NGƯỜI DÙNG: "Trình duyệt sẽ mở ra — bạn đăng nhập Gmail rồi click Cho phép nhé."

Đợi cho đến khi terminal hiện ✓ Đã lưu token.json rồi tiếp tục.

Bước 5 — Cấu hình MCP server

Ghi nhớ đường dẫn tuyệt đối tới thư mục maru-sheets-mcp vừa clone (ví dụ D:\Projects\maru-sheets-mcp hoặc /Users/ten/maru-sheets-mcp).

Thêm vào file cấu hình MCP của tool đang dùng:

Claude Code — file claude_desktop_config.json hoặc .claude.json:

{
  "mcpServers": {
    "maru-sheets": {
      "command": "node",
      "args": ["src/sheets-server.js"],
      "cwd": "<đường-dẫn-tuyệt-đối-tới-thư-mục-maru-sheets-mcp>"
    }
  }
}

Antigravity 2.0 — vào Settings → MCP Servers → thêm server mới:

• Name: maru-sheets
• Command: node
• Arguments: src/sheets-server.js
• Working directory: <đường-dẫn-tuyệt-đối-tới-thư-mục-maru-sheets-mcp>

Tool khác — tương tự, trỏ command node, args src/sheets-server.js, cwd là thư mục chứa repo.

Bước 6 — Kiểm tra

Sau khi cấu hình, restart tool (hoặc reload MCP) rồi thử:

• Gọi tool list_sheets với spreadsheetId bất kỳ mà Gmail đã auth có quyền truy cập
• Nếu trả về danh sách tab → thành công

BÁO CHO NGƯỜI DÙNG: "Đã cài xong! Bạn có thể restart Antigravity rồi thử bảo tôi đọc/ghi Sheet."

Các tool có sẵn sau khi cài

Tool	Mô tả	Tham số chính
list_sheets	Liệt kê các tab	spreadsheetId
read_range	Đọc giá trị 1 vùng (A1 notation)	spreadsheetId, range
write_range	Ghi giá trị 2D vào 1 vùng	spreadsheetId, range, values
set_formula	Set công thức vào 1 ô	spreadsheetId, cell, formula
add_sheet	Thêm tab mới	spreadsheetId, title
delete_sheet	Xoá tab	spreadsheetId, sheetTitle
rename_sheet	Đổi tên tab	spreadsheetId, oldTitle, newTitle
freeze_rows	Đóng băng N hàng đầu	spreadsheetId, sheetTitle, rows
set_format	Tô nền + chữ + bold	spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol, bgHex, fontHex, bold
set_column_width	Đặt chiều rộng cột	spreadsheetId, sheetTitle, startCol, endCol, width
merge_cells	Merge ô	spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol
set_borders	Đặt border	spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol
set_number_format	Định dạng số/ngày	spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol, pattern
set_data_validation	Dropdown validation	spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol, values
set_conditional_format	Conditional formatting	spreadsheetId, sheetTitle, range, type, values, bgHex
set_text_wrap_align	Wrap text + căn chỉnh	spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol
set_protected_range	Bảo vệ vùng	spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol
apply_template	Áp nhiều request 1 lúc (batchUpdate)	spreadsheetId, requests

Lưu ý kỹ thuật

• Công thức Google Sheets locale Việt Nam dùng dấu ; thay , — ví dụ: =IF(A1>5;"Đạt";"Chưa đạt")
• spreadsheetId lấy từ URL: https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit
• Muốn truy cập Sheet của người khác → người đó phải share (Viewer/Editor) cho Gmail đã auth
• set_format dùng gridRange 0-based (hàng/cột bắt đầu từ 0)

Xử lý lỗi thường gặp

Lỗi	Nguyên nhân	Cách sửa
Chưa có token.json	Chưa chạy auth	npm run auth
insufficient permission	Sheet chưa share cho Gmail	Mở Sheet → Share → thêm Gmail
Không thấy tab "..."	Tên tab sai	Kiểm tra tên chính xác (có dấu, khoảng trắng)
node: command not found	Chưa cài Node.js	Cài Node.js theo Bước 0
git: command not found	Chưa cài Git	Cài Git theo Bước 1
ECONNREFUSED / invalid_grant	Token hết hạn	Xoá token.json, chạy lại npm run auth