Skip to content
Back to search

google-tasks-mcp-server

MCP server for Google Tasks

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/doquannnn--google-tasks-mcp-server/badge.svg)](/listings/doquannnn--google-tasks-mcp-server)

HTML

<a href="/listings/doquannnn--google-tasks-mcp-server"><img src="/api/listings/doquannnn--google-tasks-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 148 lines
  1. # Google Tasks MCP server (tự host)
  2. MCP server cho Google Tasks, viết theo kiểu [todoist/todoist-mcp](https://github.com/todoist/todoist-mcp): tool nhận input dạng mảng (batch), có `find-*` / `add-*` / `update-*` / `delete-object`. Viết bằng TypeScript, dùng `@modelcontextprotocol/sdk` 1.32 và zod. Node ≥ 23.6 chạy thẳng file `.ts` nên không cần bước build. Chỉ có 2 dependency.
  3. ## 1. Tìm hiểu: các cách host một MCP server
  4. | Cách | Transport | Khi nào dùng | Ghi chú |
  5. |---|---|---|---|
  6. | **Local stdio** | stdio | Một máy, một người dùng (Claude Code/Desktop, Cursor) | Client tự spawn process, không mở cổng, đơn giản và an toàn nhất |
  7. | **Local HTTP** | Streamable HTTP trên `127.0.0.1` | Nhiều client trên cùng máy, hoặc thử trước khi deploy | Bảo vệ bằng bearer token |
  8. | **Cloudflare Workers** | Streamable HTTP | Remote, miễn phí ở mức nhỏ | Có template và OAuth provider sẵn, chạy runtime Workers (không phải Node đầy đủ) |
  9. | **Google Cloud Run** | Streamable HTTP (không hỗ trợ stdio) | Remote, hợp với hệ Google, scale về 0 | Deploy container, có URL HTTPS sẵn |
  10. | Fly.io / Render / Railway / Vercel | Streamable HTTP | Remote, deploy từ git hoặc Docker | Tương tự Cloud Run |
  11. Các điểm chính:
  12. - **Transport chuẩn hiện tại** là *stdio* (local) và *Streamable HTTP* (remote). Transport HTTP+SSE cũ đã bị thay thế.
  13. - **Auth cho remote server:** spec MCP dùng OAuth 2.1. Todoist hosted (`https://ai.todoist.net/mcp`) dùng OAuth; khi chạy local thì dùng API key qua env. Server cá nhân dùng một mình thì bearer token + HTTPS là đủ.
  14. - **Stateless HTTP** (mỗi request tạo một server/transport mới) là cách đơn giản và scale ngang dễ trên serverless. Server này đang làm như vậy.
  15. Nguồn: [Cloud Run – Host MCP servers](https://docs.cloud.google.com/run/docs/host-mcp-servers), [Cloudflare – Remote MCP server](https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/index.md), [Fly.io – Host a remote MCP server](https://fly.io/learn/host-a-remote-mcp-server/), [Modal – platforms for Streamable HTTP MCP](https://modal.com/resources/best-platforms-streamable-http-mcp-servers), [todoist-mcp](https://github.com/todoist/todoist-mcp).
  16. ## 2. Các tool
  17. | Tool | Tương ứng Todoist | Mô tả |
  18. |---|---|---|
  19. | `find-tasklists` | find-projects | Liệt kê list, có lọc theo tên |
  20. | `add-tasklists` | add-projects | Tạo nhiều list. Bỏ qua list trùng tên (idempotent) |
  21. | `update-tasklists` | update-projects | Đổi tên list |
  22. | `find-tasks` | find-tasks | Tìm task theo list, từ khoá, parent, có/không lấy task đã xong. Tự lấy hết các trang |
  23. | `find-tasks-by-date` | find-tasks-by-date | Task theo khoảng ngày, hoặc `overdue: true` để lấy task quá hạn |
  24. | `add-tasks` | add-tasks | Tạo nhiều task: notes, ngày hạn, subtask (`parentId`), vị trí |
  25. | `update-tasks` | update-tasks | Sửa tiêu đề, notes, ngày hạn (`null` để xoá) |
  26. | `complete-tasks` / `uncomplete-tasks` | complete/uncomplete-tasks | Đánh dấu xong / mở lại |
  27. | `move-task` | project-move | Sắp xếp lại, lồng hoặc gỡ subtask, chuyển sang list khác |
  28. | `delete-object` | delete-object | Xoá task hoặc cả list |
  29. | `get-overview` | get-overview | Đếm task đang mở, quá hạn và đến hạn hôm nay của từng list |
  30. Tham số `tasklist` nhận **ID hoặc tên list** (vd `"Hàng tạp hóa"`), để LLM gọi dễ hơn.
  31. **Giới hạn của Google Tasks API** (so với Apple Reminders/Todoist):
  32. - Hạn chỉ lưu **ngày**, phần giờ bị bỏ.
  33. - Không có lặp lại, ưu tiên hay label.
  34. Khi import, giờ và kiểu lặp lại được ghi vào `notes` (vd `Giờ: 10:00 · Lặp lại: Hằng tuần`).
  35. ## 3. Kết nối với tài khoản Google của bạn — cần bạn làm
  36. Mình không thể tạo OAuth client thay bạn, vì việc này cần đăng nhập Google Cloud Console. Làm một lần, khoảng 5 phút:
  37. 1. Vào https://console.cloud.google.com/ và tạo project mới, vd `personal-mcp`.
  38. 2. Vào **APIs & Services → Library** và Enable **Google Tasks API**.
  39. 3. Vào **Google Auth Platform → Branding / Audience** (tức OAuth consent screen):
  40. - User type: **External**, trạng thái **Testing**.
  41. - Ở **Test users**, thêm Gmail của bạn.
  42. 4. Vào **Data Access → Add scope** và thêm `https://www.googleapis.com/auth/tasks`.
  43. 5. Vào **Clients → Create client**, chọn Application type **Desktop app**, rồi **Download JSON**.
  44. 6. Lưu file JSON đó thành `credentials.json` trong thư mục này. **Đừng dán nội dung vào chat.** File đã có trong `.gitignore`.
  45. 7. Chạy lệnh sau, mở link được in ra và đồng ý quyền:
  46. ```bash
  47. npm run auth
  48. ```
  49. Lệnh này tạo `token.json` (chmod 600) chứa refresh token.
  50. > ⚠️ Khi app ở trạng thái **Testing**, Google cho refresh token **hết hạn sau 7 ngày**. Hết hạn thì chạy lại `npm run auth`. Muốn token dùng lâu dài, bấm **Publish app** (chế độ In production). App cá nhân chưa qua xác minh vẫn dùng được, chỉ hiện cảnh báo "unverified" lúc đăng nhập.
  51. ## 4. Chạy và test
  52. ```bash
  53. npm install
  54. ```
  55. Test offline với mock Google API: import `data/reminders.md`, chạy CRUD, kiểm tra HTTP và token.
  56. ```bash
  57. npm test
  58. ```
  59. Khi đã có `credentials.json` và `token.json`, chạy với tài khoản thật. Lệnh import chạy lại nhiều lần cũng không bị trùng. Phần CRUD chỉ chạy trên một list tạm, list này bị xoá ở cuối.
  60. ```bash
  61. npm run test:real
  62. ```
  63. Hoặc chỉ import:
  64. ```bash
  65. npm run import
  66. ```
  67. Hoàn tác import. Lệnh này chỉ xoá những gì import đã tạo, theo ghi chép trong `.import-state.json`: các list do import tạo mới, và các task import đã thêm vào list có sẵn. Dữ liệu cũ của bạn, kể cả list trùng tên như "Work", được giữ nguyên.
  68. ```bash
  69. npm run import:undo
  70. ```
  71. ### Dùng hằng ngày: chat với Claude để thao tác Google Tasks
  72. ```bash
  73. ./start.sh
  74. ```
  75. Script kiểm tra token Google (tự chạy lại `npm run auth` nếu hết hạn), rồi chạy server HTTP ở foreground tại `http://127.0.0.1:8787/mcp`. Server sống cho tới khi bạn bấm **Ctrl+C** ở terminal đó.
  76. Mở Claude trong thư mục này ở tab/cửa sổ khác (terminal hoặc app desktop). `.mcp.json` khai báo server `google-tasks` kiểu `http`, nên Claude chỉ kết nối tới server đang chạy chứ không tự bật nó. Nếu chưa chạy `./start.sh`, server sẽ hiện là lỗi kết nối. Nếu bật server sau khi đã mở Claude, gõ `/mcp` để kết nối lại. Lần đầu, Claude sẽ hỏi có cho phép MCP server của project không: chọn đồng ý. `CLAUDE.md` hướng dẫn Claude cách dùng các tool (múi giờ, ghi giờ vào notes, xác nhận trước khi xoá).
  77. **Bearer token:** server và Claude dùng chung token trong `.mcp-token` (chmod 600, đã có trong `.gitignore`). `start.sh` đưa token vào `MCP_AUTH_TOKEN`, còn `.mcp.json` đọc nó qua `headersHelper`. Token chặn các trang web hay tiến trình khác trên máy gọi vào server. Tạo hoặc đổi token:
  78. ```bash
  79. (umask 077; openssl rand -hex 32 > .mcp-token)
  80. ```
  81. ### Gắn vào client khác
  82. Mẫu cấu hình nằm ở `.mcp.json.example`:
  83. - **stdio:** `node /đường/dẫn/src/server.ts`
  84. - **HTTP local:** chạy `MCP_AUTH_TOKEN=... npm run http`, rồi trỏ client tới `http://127.0.0.1:8787/mcp` kèm header `Authorization: Bearer ...`
  85. ### Deploy lên Cloud Run (tuỳ chọn)
  86. ```bash
  87. gcloud run deploy google-tasks-mcp --source . --region asia-southeast1 \
  88. --set-env-vars GOOGLE_CLIENT_ID=...,GOOGLE_CLIENT_SECRET=...,GOOGLE_REFRESH_TOKEN=...,MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  89. --allow-unauthenticated
  90. ```
  91. Nên đưa các secret vào Secret Manager thay vì `--set-env-vars`. Server từ chối listen trên `0.0.0.0` nếu thiếu `MCP_AUTH_TOKEN`.
  92. ## 5. Cách import `reminders.md` được map
  93. - **6 list:** Me, Work, Subscription, Todo, Reminder, Hàng tạp hóa.
  94. - **Bảng "Có hạn":** mỗi dòng vào list ở cột *Danh sách*, kèm ngày hạn. Giờ, kiểu lặp lại và cờ "quá hạn" ghi vào notes.
  95. - **Todo:** "Sắp xếp lại ứng dụng mật khẩu" (3 việc con) và "Tìm hiểu Deco" (5 việc con) thành task cha có subtask thật. Phần `*(...)*` chuyển thành notes.
  96. - **Reminder:**
  97. - *Hermes Agent – Personal Assistant* là nhóm thật trong app, nên thành task cha với 12 subtask.
  98. - Các nhóm khác chỉ là gợi ý (file có ghi chú vậy), nên task để phẳng, notes ghi `Nhóm: ...`.
  99. - **Về số lượng:** header file ghi 65 nhắc nhở, nhưng file chỉ liệt kê **64**. Mục Reminder ghi (32) nhưng có 31 dòng. Bản import tạo 64 task + 1 task cha "Hermes Agent", tổng **65 task**.
  100. ## Cấu trúc
  101. ```
  102. src/server.ts entry: stdio (mặc định) hoặc --http (Streamable HTTP, stateless, bearer token)
  103. src/tools.ts 12 MCP tools
  104. src/google-tasks.ts client REST tối giản: refresh token, phân trang
  105. scripts/auth.ts OAuth loopback + PKCE → token.json
  106. scripts/import-reminders.ts import reminders.md qua chính các MCP tool
  107. test/mock-google.ts giả lập Google Tasks API (due chỉ lưu ngày, phân trang 20/100, @default không xoá được)
  108. test/e2e.ts test end-to-end
  109. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.