google-workspace-mcp

MCP server kết nối Claude với Google Sheets, Google Docs và Google Drive.

Khác với connector Google Drive mặc định (chỉ đọc/ghi file), server này đọc & ghi được từng ô trong Google Sheets: viết công thức, định dạng, chèn/xoá hàng cột, tạo dropdown, biểu đồ, conditional format…

Chạy hoàn toàn trên máy bạn, bằng tài khoản Google Cloud của chính bạn. Không có máy chủ trung gian, dữ liệu không đi qua bên thứ ba.

Cài đặt

Cách 1 — Claude Desktop (dễ nhất)

Tải file .mcpb ở mục Releases → double-click → Install. Rồi mở chat gõ "Hướng dẫn mình kết nối Google", Claude sẽ dẫn từng bước.

Cách 2 — Chạy từ mã nguồn

git clone https://github.com/<user>/google-workspace-mcp.git
cd google-workspace-mcp
npm install

Tạo OAuth client của riêng bạn (miễn phí, ~10 phút, làm 1 lần):

1. Vào Google Cloud Console → tạo project mới.
2. APIs & Services → Library → Enable 3 API: Google Sheets API, Google Docs API, Google Drive API.
3. APIs & Services → OAuth consent screen → chọn External → điền tên app → ở mục Audience, thêm email của bạn vào Test users.
4. APIs & Services → Credentials → Create Credentials → OAuth client ID → chọn Desktop app → Create → Download JSON.
5. Đổi tên file vừa tải thành credentials.json, đặt vào thư mục gốc của project (xem mẫu ở credentials.example.json).

Đăng nhập:

npm run auth

Trình duyệt mở ra → đăng nhập tài khoản Google → token lưu vào token.json (tự refresh, không cần làm lại).

Google hiện "Google hasn't verified this app"? Bình thường — app này do chính bạn vừa tạo. Bấm Advanced → Go to … (unsafe) → Continue.

Khai báo server trong file cấu hình MCP của Claude:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/đường/dẫn/tới/google-workspace-mcp/index.js"]
    }
  }
}

Bảo mật

• credentials.json và token.json chứa bí mật của bạn — đã được .gitignore, đừng bao giờ commit hay chia sẻ.
• token.json cho phép truy cập Google account của bạn mà không cần mật khẩu. Coi nó như mật khẩu.
• Mỗi người dùng nên tạo OAuth client riêng, không dùng chung.

Tools

Drive (10)

Tool	Chức năng
drive_search	Tìm file/thư mục theo tên → lấy id
drive_list_folder	Liệt kê nội dung thư mục
drive_create_folder	Tạo thư mục
drive_move / drive_copy / drive_rename	Di chuyển / nhân bản / đổi tên
drive_trash	Chuyển vào thùng rác (khôi phục được, không xoá vĩnh viễn)
drive_export	Tải về máy: Docs/Sheets → pdf/docx/xlsx/csv/pptx/txt/html
drive_upload	Upload file lên Drive, convert xlsx/csv → Sheets, docx → Docs
drive_share	Chia sẻ cho email hoặc bật link công khai

Sheets (18)

Tool	Chức năng
sheets_get_metadata	Danh sách tab, kích thước, freeze
sheets_read	Đọc 1 range hoặc nhiều ranges, tuỳ chọn đọc công thức
sheets_write / sheets_append / sheets_clear	Ghi / thêm hàng / xoá giá trị
sheets_format	Đậm/nghiêng, font, cỡ chữ, màu chữ/nền, căn lề, định dạng số, wrap, border, freeze, độ rộng cột
sheets_manage_tab	Đổi tên / nhân bản / ẩn-hiện / màu tab / xoá tab
sheets_insert_delete_rows_columns	Chèn/xoá hàng, cột
sheets_merge_cells	Gộp/tách ô
sheets_sort_range	Sắp xếp theo cột
sheets_find_replace	Tìm & thay thế
sheets_conditional_format	Tô màu theo điều kiện (>, <, chứa chữ, công thức...)
sheets_dropdown	Tạo dropdown chọn giá trị
sheets_add_chart	Vẽ biểu đồ COLUMN/BAR/LINE/AREA/PIE
sheets_copy_tab_to	Copy tab sang spreadsheet khác
sheets_create / sheets_add_tab	Tạo file / tab mới
sheets_batch_update	Raw API cho nhu cầu nâng cao (pivot, protected range...)

Docs (8)

Tool	Chức năng
docs_read	Đọc TẤT CẢ tab (tabId + tiêu đề + nội dung; heading → #, bullet → -)
docs_create / docs_append	Tạo / thêm nội dung markdown (# heading, đậm, nghiêng, - bullet, 1. số), ghi được vào từng tab
docs_replace_text	Tìm & thay thế toàn bộ hoặc trong 1 tab (điền template)
docs_format_text	Định dạng chuỗi tìm thấy: đậm, nghiêng, gạch chân, cỡ chữ, font, màu, highlight, gắn link
docs_insert_table	Chèn bảng kèm dữ liệu
docs_insert_image	Chèn ảnh từ URL
docs_batch_update	Raw API cho nhu cầu nâng cao (header/footer, page break...)

Cấu hình (env, tuỳ chọn)

• GOOGLE_OAUTH_CREDENTIALS — đường dẫn file client secret (mặc định: ./credentials.json, copy từ vivian/credentials.json)
• GOOGLE_OAUTH_TOKEN — đường dẫn file token (mặc định: ./token.json)