# 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](../../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

```bash
git clone https://github.com/haule2901/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](https://console.cloud.google.com) → 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:**

```bash
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:

```json
{
  "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`)
- `GOOGLE_OAUTH_TOKEN` — đường dẫn file token (mặc định: `./token.json`)