ticktick-mcp-ratv

# TickTick MCP 服务器 [](LICENSE) [](https://www.typescriptlang.org) [](https://modelcontextprotocol.io) [](https://nodejs.org) 一个 [MCP](https://modelcontextprotocol.io) 服务器，允许您的 AI 助手通过自然语言管理您的 [TickTick](https://ticktick.com) 任务、项目、习惯等。适用于 **Claude Code**、**Cursor**、**VS Code**、**Claude Desktop** 和任何 MCP 兼容的客户端。 还支持 **Dida365**（TickTick 的中文版）。 --- ## 功能 **52 种工具**，涵盖两层 API： | 类别 | 工具 | API | | --- | --- | --- | | **项目** | 列出、创建、更新、删除 | V1 | | **任务** | CRUD、批量创建、完成、子任务 | V1 | | **智能查询** | 今日、明日、本周到期、逾期、按优先级 | V1 | | **搜索和筛选** | 全文搜索、多条件筛选 | V1 | | **GTD 工作流** | 已参与任务、下一个动作、每日摘要 | V1 | | **标签** | 列出、创建、重命名、删除、合并 | V2 | | **习惯** | 创建、签到、查看记录和历史 | V2 | | **专注/番茄** | 热图、时间分布、生产力评分 | V2 | | **已完成任务** | 浏览已完成的任务，日期筛选 | V2 | | **看板列** | 管理看板项目中的列 | V2 | | **项目文件夹** | 将项目组织成组 | V2 | | **任务组织** | 在项目之间移动任务，子任务层次 | V2 | | **用户配置文件** | 配置文件信息、时区、设置 | V2 | > **V1** = 官方 TickTick 开放 API（OAuth2）。**V2** = 内部 API（会话身份验证），适用于公共 API 中没有的功能。 --- ## 安装 ### 1. 创建 TickTick 开发者应用 1. 访问 [developer.ticktick.com/manage](https://developer.ticktick.com/manage) 2. 点击 **+ 创建应用** 3. 将 **重定向 URI** 设置为：`http://localhost:42813/callback` 4. 记录您的 **客户端 ID** 和 **客户端密钥** ### 2. 安装和身份验证 ```bash git clone https://github.com/chrisvanek/ticktick-mcp-ratv.git cd ticktick-mcp-ratv npm install && npm run build # 运行交互式设置向导 node build/index.js auth ``` 向导将引导您完成： 1. **TickTick 登录**（电子邮件 + 密码）— 启用 V2 功能（标签、习惯、专注、已完成任务） 2. **OAuth2 流程**（客户端 ID + 密钥 + 浏览器身份验证）— 启用 V1 功能（项目、任务） 凭证将保存到本地 `.env` 文件中（不提交到 git）。 ### 3. 连接到您的 AI 客户端 将服务器添加到您的 MCP 客户端配置中。替换 `.env` 文件中的凭证： <details> <summary><strong>Claude Code</strong></summary> **CLI（推荐）：** ```bash claude mcp add ticktick-mcp-server \ node /绝对路径/to/ticktick-mcp-ratv/build/index.js \ -e TICKTICK_CLIENT_ID=您的客户端ID \ -e TICKTICK_CLIENT_SECRET=您的客户端密钥 \ -e TICKTICK_ACCESS_TOKEN=您的访问令牌 \ -e TICKTICK_REFRESH_TOKEN=您的刷新令牌 \ -e TICKTICK_USERNAME=您的电子邮件 \ -e TICKTICK_PASSWORD=您的密码 \ -e TICKTICK_DEVICE_ID=您的设备ID \ -s user ``` 使用 `-s user`（在所有地方都可用）、`-s project`（与团队共享）或 `-s local`（单个项目）。 **配置文件**（`~/.claude.json` 或 `.mcp.json`）： ```json { "mcpServers": { "ticktick": { "command": "node", "args": ["/绝对路径/to/ticktick-mcp-ratv/build/index.js"], "env": { "TICKTICK_CLIENT_ID": "您的客户端ID", "TICKTICK_CLIENT_SECRET": "您的客户端密钥", "TICKTICK_ACCESS_TOKEN": "您的访问令牌", "TICKTICK_REFRESH_TOKEN": "您的刷新令牌", "TICKTICK_USERNAME": "您的电子邮件", "TICKTICK_PASSWORD": "您的密码", "TICKTICK_DEVICE_ID": "您的设备ID" } } } } ``` 在 Claude Code 中使用 `/mcp` 验证。 </details> <details> <summary><strong>Cursor</strong></summary> 创建或编辑 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目）： ```json { "mcpServers": { "ticktick": { "command": "node", "args": ["/绝对路径/to/ticktick-mcp-ratv/build/index.js"], "env": { "TICKTICK_CLIENT_ID": "您的客户端ID", "TICKTICK_CLIENT_SECRET": "您的客户端密钥", "TICKTICK_ACCESS_TOKEN": "您的访问令牌", "TICKTICK_REFRESH_TOKEN": "您的刷新令牌", "TICKTICK_USERNAME": "您的电子邮件", "TICKTICK_PASSWORD": "您的密码", "TICKTICK_DEVICE_ID": "您的设备ID" } } } } ``` 重启 Cursor 后生效。 </details> <details> <summary><strong>VS Code（Copilot 代理模式）</strong></summary> 需要 VS Code 1.99+ 和 GitHub Copilot。创建 `.vscode/mcp.json`: ```json { "servers": { "ticktick": { "command": "node", "args": ["/绝对路径/to/ticktick-mcp-ratv/build/index.js"], "env": { "TICKTICK_CLIENT_ID": "您的客户端ID", "TICKTICK_CLIENT_SECRET": "您的客户端密钥", "TICKTICK_ACCESS_TOKEN": "您的访问令牌", "TICKTICK_REFRESH_TOKEN": "您的刷新令牌", "TICKTICK_USERNAME": "您的电子邮件", "TICKTICK_PASSWORD": "您的密码", "TICKTICK_DEVICE_ID": "您的设备ID" } } } } ``` </details> <details> <summary><strong>Claude Desktop</strong></summary> 编辑配置文件： - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%AppData%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "ticktick": { "command": "node", "args": ["/绝对路径/to/ticktick-mcp-ratv/build/index.js"], "env": { "TICKTICK_CLIENT_ID": "您的客户端ID", "TICKTICK_CLIENT_SECRET": "您的客户端密钥", "TICKTICK_ACCESS_TOKEN": "您的访问令牌", "TICKTICK_REFRESH_TOKEN": "您的刷新令牌", "TICKTICK_USERNAME": "您的电子邮件", "TICKTICK_PASSWORD": "您的密码", "TICKTICK_DEVICE_ID": "您的设备ID" } } } } ``` 退出并重启 Claude Desktop（Cmd+Q / Alt+F4）。 </details> ### Dida365（中国） 将 `TICKTICK_HOST=dida365` 添加到您的环境变量中。这将使 API 调用路由到 `api.dida365.com`。 ### 节点版本管理器（nvm、fnm 等） 如果您的 MCP 客户端中 `node` 未解析，请使用完整路径： ```json "command": "/Users/您/.nvm/versions/node/v22.0.0/bin/node" ``` --- ## 使用示例 连接后，只需自然地说话。以下是按功能组织的示例： ### 早晨规划 > "给我每日总结" > "什么逾期了？" > "我本周有什么任务？" > "显示所有高优先级任务" ### 创建任务 > "在我的工作项目中创建一个名为'Review PR #42'的任务，明天到期，高优先级" > "在个人项目中添加一个任务'买杂货'，并包含子任务：牛奶、鸡蛋、面包、黄油" > "在我的工作项目中创建一个每周一次的 recurring 任务'周报笔记'" > "在我的工作项目中创建以下任务：查看设计模型、更新 API 文档、修复登录错误" ### 管理任务 > "将'Send invoice' 任务标记为完成" > "将'Design review' 移动到我的工作项目" > "将'Write tests' 设置为'Ship v2' 的子任务" > "我上周完成了哪些任务？" ### 搜索和筛选 > "搜索任何提及'budget' 的任务" > "显示所有中等优先级任务" > "接下来的 3 天内有哪些任务到期？" > "显示个人项目中所有有到期日的任务" ### 项目 > "列出所有我的项目" > "创建一个名为'Q2 Goals' 的新项目，使用看板视图" > "显示我的工作项目中的所有内容 - 任务、列等" ### 标签 > "显示所有我的标签" > "创建一个名为'urgent' 的标签，颜色为红色" > "将'bug' 标签重命名为'bugfix'" > "将'todo' 标签合并到'backlog'" ### 习惯 > "我有哪些习惯？" > "签到我的'Drink water' 习惯" > "创建一个名为'Read' 的习惯，目标是每天 30 页" > "显示我所有习惯的签到记录，自 January 以来" ### 专注和生产力 > "显示我这个月的专注时间热图" > "我的专注时间如何分布在标签上？" > "我的生产力统计数据是什么？" ### 组织 > "列出我的项目文件夹" > "创建一个名为'Side Projects' 的文件夹" > "显示我的 Sprint 项目中的看板列" > "我的垃圾桶里有什么？" --- ## 环境变量 | 变量 | 必需 | 描述 | | --- | --- | --- | | `TICKTICK_CLIENT_ID` | 是 | OAuth2 客户端 ID 来自开发者门户 | | `TICKTICK_CLIENT_SECRET` | 是 | OAuth2 客户端密钥 | | `TICKTICK_ACCESS_TOKEN` | 是 | OAuth2 访问令牌（由身份验证向导设置） | | `TICKTICK_REFRESH_TOKEN` | 否 | OAuth2 刷新令牌（启用自动续期） | | `TICKTICK_USERNAME` | 是 | 您的 TickTick 电子邮件（适用于 V2 API） | | `TICKTICK_PASSWORD` | 是 | 您的 TickTick 密码（适用于 V2 API） | | `TICKTICK_DEVICE_ID` | 推荐 | 稳定的 24 字符十六进制设备 ID，用于 V2 `x-device` 请求头（参见下面的备注） | | `TICKTICK_HOST` | 否 | `ticktick`（默认）或 `dida365` 用于中国 | > **安全备注：** V2 API 需要您的 TickTick 用户名和密码。这些存储为环境变量，永远不会被记录或传输到除 TickTick 身份验证端点以外的任何地方。`.env` 文件以限制权限创建（仅所有者可读/写）。 > **`TICKTICK_DEVICE_ID` 备注：** V2 内部 API 通过 `x-device` 请求头验证“设备”。如果设备 ID 为空或无法识别，TickTick 会以 **误导性的 `username_password_not_match` 错误** 拒绝登录 - 即使您的凭证正确。服务器发送一个非空的设备 ID 以避免此问题。如果您不设置 `TICKTICK_DEVICE_ID`，每次启动都会自动生成一个随机的 24 个字符的十六进制 ID；建议设置一个 **稳定的** 值，以便 TickTick 不会将每次重启视为一个全新的设备。任何 24 个字符的十六进制字符串都有效 - 或重用您的 TickTick Web 客户端已使用的 ID（浏览器开发工具 → 应用程序 → 本地存储 → `deviceAnalyticsData.id`）。 --- ## 所有 52 种工具 <details> <summary><strong>项目管理</strong>（6 种工具，V1）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_projects` | 列出所有项目 | | `ticktick_get_project` | 通过 ID 获取项目 | | `ticktick_get_project_data` | 获取包含任务和列的项目 | | `ticktick_create_project` | 创建项目 | | `ticktick_update_project` | 更新项目属性 | | `ticktick_delete_project` | 删除项目 | </details> <details> <summary><strong>任务管理</strong>（6 种工具，V1）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_task` | 通过 ID 获取任务 | | `ticktick_create_task` | 创建任务并包含所有选项 | | `ticktick_update_task` | 更新任务字段 | | `ticktick_complete_task` | 标记任务为完成 | | `ticktick_delete_task` | 删除任务 | | `ticktick_batch_create_tasks` | 一次创建多个任务 | </details> <details> <summary><strong>智能查询和 GTD</strong>（12 种工具，V1）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_all_tasks` | 所有未完成的任务，跨所有项目 | | `ticktick_search_tasks` | 全文搜索 | | `ticktick_get_tasks_due_today` | 今日到期任务 | | `ticktick_get_tasks_due_tomorrow` | 明天到期任务 | | `ticktick_get_tasks_due_this_week` | 7 天内到期任务 | | `ticktick_get_tasks_due_in_days` | N 天内到期任务 | | `ticktick_get_overdue_tasks` | 逾期任务 | | `ticktick_get_tasks_by_priority` | 按优先级过滤 | | `ticktick_filter_tasks` | 高级多条件过滤 | | `ticktick_get_engaged_tasks` | GTD“参与”列表 | | `ticktick_get_next_tasks` | GTD“下一个”列表 | | `ticktick_daily_summary` | 完整的每日摘要 | </details> <details> <summary><strong>标签</strong>（5 种工具，V2）</summary> | 工具 | 描述 | | | --- | | `ticktick_get_tags` | 列出所有标签 | | `ticktick_create_tag` | 创建标签 | | `ticktick_rename_tag` | 重命名标签 | | `ticktick_delete_tag` | 删除标签 | | `ticktick_merge_tags` | 合并一个标签到另一个 | </details> <details> <summary><strong>习惯</strong>（6 种工具，V2）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_habits` | 列出所有习惯 | | `ticktick_get_habit_sections` | 获取习惯部分 | | `ticktick_create_habit` | 创建习惯 | | `ticktick_delete_habit` | 删除习惯 | | `ticktick_checkin_habit` | 签到习惯 | | `ticktick_get_habit_checkins` | 查看签到记录 | </details> <details> <summary><strong>专注/番茄</strong>（3 种工具，V2）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_focus_heatmap` | 专注时间热图 | | `ticktick_get_focus_distribution` | 按类别分布的专注时间 | | `ticktick_get_productivity_stats` | 生产力得分和统计数据 | </details> <details> <summary><strong>已完成和回收站任务</strong>（2 种工具，V2）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_completed_tasks` | 浏览已完成的任务 | | `ticktick_get_trashed_tasks` | 查看已删除的任务 | </details> <details> <summary><strong>任务组织</strong>（2 种工具，V2）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_move_task` | 移动任务到另一个项目 | | `ticktick_set_task_parent` | 设置/删除子任务关系 | </details> <details> <summary><strong>看板和文件夹</strong>（8 种工具，V2）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_columns` | 列出看板列 | | `ticktick_create_column` | 创建列 | | `ticktick_delete_column` | 删除列 | | `ticktick_move_task_to_column` | 移动任务到另一个看板列 | | `ticktick_get_project_folders` | 列出项目文件夹 | | `ticktick_create_project_folder` | 创建文件夹 | | `ticktick_delete_project_folder` | 删除文件夹 | | `ticktick_move_project_to_folder` | 将列表移动到/从文件夹 | </details> <details> <summary><strong>用户和设置</strong>（2 种工具，V2）</summary> | 工具 | 描述 | | --- | --- | | `ticktick_get_user_profile` | 配置文件，电子邮件，时区，订阅 | | `ticktick_get_user_settings` | 账户偏好 | </details> --- ## 参考 **任务优先级值：** `0` = 无，`1` = 低，`3` = 中，`5` = 高 **日期格式：** `yyyy-MM-dd'T'HH:mm:ssZ`（例如 `2025-03-15T09:00:00+0000`） **循环规则：** 标准 RRULE 格式（例如 `RRULE:FREQ=DAILY;INTERVAL=1`） --- ## 开发 ```bash npm install # 安装依赖 npm run build # 编译 TypeScript npm run dev # 监视模式 npm run clean # 删除构建输出 ``` ### 添加工具 1. 在 `src/tools/` 下的相应文件中添加您的工具。 2. 使用 Zod 输入模式使用 `server.registerTool()`。 3. 它会自动对所有 MCP 客户端可用。 ### 架构 ``` src/ ├── index.ts # 入口点 + 身份验证 CLI 路由 ├── config.ts # 环境变量加载器 ├── client.ts # V1 API 客户端（OAuth2） ├── client-v2.ts # V2 API 客户端（会话身份验证） ├── types.ts # TypeScript 接口 ├── auth-cli.ts # 交互式身份验证向导 ├── auth/oauth.ts # OAuth2 流实现 └── tools/ ├── project-tools.ts # 项目 CRUD（V1） ├── task-tools.ts # 任务 CRUD（V1） ├── smart-tools.ts # 智能查询和 GTD（V1） ├── tag-tools.ts # 标签管理（V2） ├── habit-tools.ts # 习惯跟踪（V2） ├── focus-tools.ts # 专注/番茄统计（V2） ├── column-tools.ts # 看板列（V2） ├── folder-tools.ts # 项目文件夹（V2） └── v2-task-tools.ts # 已完成任务，移动，用户（V2） ``` 两个 API 客户端都透明地处理身份验证 - 过期的令牌会在 401 响应时自动刷新。 --- ## 故障排除 | 问题 | 修复 | | --- | --- | | “缺少必需的环境变量” | 运行 `node build/index.js auth` 或在 MCP 配置中设置变量 | | “令牌刷新失败” / 401 错误 | 重新运行 `node build/index.js auth` | | 服务器未在 Claude Code 中显示 | 使用绝对路径，检查 `/mcp`，尝试 `claude mcp remove` + `add` | | 服务器未在 Cursor 中显示 | 重启 Cursor，检查输出面板 > MCP | --- ## 贡献 1. 复刻仓库 2. 创建一个功能分支 3. 进行更改并运行 `npm run build` 4. 打开一个拉取请求 --- ## 许可证 MIT - 参见 [LICENSE](LICENSE)。 ## 致谢 - [TickTick 开放 API](https://developer.ticktick.com) - [模型上下文协议](https://modelcontextprotocol.io) - 灵感来自 [jacepark12/ticktick-mcp](https://github.com/jacepark12/ticktick-mcp) 和 [jen6/ticktick-mcp](https://github.com/jen6/ticktick-mcp)