AI导哈

任务管理MCP服务器

一个通过自然语言让AI助手管理TickTick任务、项目和习惯的MCP服务器，适用于多种开发工具和客户端。

  • by ChrisJVanek
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 ChrisJVanek/ticktick-mcp-ratv

使用说明

TickTick MCP服务器

一 主控程序 服务器，让您的AI助手管理您的 TickTick 通过自然语言完成任务、项目、习惯等。适用于 克劳德代码, 光标, VS Code, 克劳德桌面版，以及任何兼容MCP的客户端。

还支持 Dida365 （TickTick的中文版本）。

特征

52工具 跨越两个API层：

类别 工具 API
项目 列出、创建、更新、删除 V1
任务 CRUD、批创建、完成、子任务 V1
智能查询 按优先级排列，今天/明天/本周到期，逾期 V1
搜索和筛选 全文搜索，多条件过滤 V1
GTD工作流程 已完成的任务、下一步行动、每日摘要 V1
标签 列出、创建、重命名、删除、合并 V2
习惯 创建、签入、查看条纹和历史记录 V2
焦点/番茄 热图、时间分布、生产率得分 V2
已完成的任务 使用日期筛选浏览已完成的任务 V2
看板栏 管理看板项目中的列 V2
项目文件夹 将项目分组 V2
任务组织 在项目、子任务层次结构之间移动任务 V2
用户档案 个人资料信息、时区、设置 V2

第1版 =官方TickTick Open API（OAuth2）。 V-2型 =不在公共API中的功能的内部API（会话身份验证）。

设置

1.创建TickTick开发者应用程序

  1. 首选 developer.ticktick.com/manager
  2. 点击 +创建应用程序
  3. 集 重定向URI 致： http://localhost:42813/callback
  4. 注意你的 客户端ID 和 客户端密钥

2.安装并验证

git clone https://github.com/chrisvanek/ticktick-mcp-ratv.git
cd ticktick-mcp-ratv
npm install && npm run build

# Run the interactive setup wizard
node build/index.js auth

向导将指导您完成以下操作：

  1. TickTick登录 （电子邮件+密码）--启用V2功能（标签、习惯、焦点、已完成的任务）
  2. OAuth2流 （客户端ID+密码+浏览器身份验证）-启用V1功能（项目、任务）

凭据保存到本地 .env 文件（从git中排除）。

3.连接到您的AI客户端

将服务器添加到MCP客户端配置中。用您的凭据替换占位符值 .env 文件。

Claude Code

CLI（推荐）：

claude mcp add ticktick-mcp-server \
  node /absolute/path/to/ticktick-mcp-ratv/build/index.js \
  -e TICKTICK_CLIENT_ID=your_client_id \
  -e TICKTICK_CLIENT_SECRET=your_client_secret \
  -e TICKTICK_ACCESS_TOKEN=your_access_token \
  -e TICKTICK_REFRESH_TOKEN=your_refresh_token \
  -e TICKTICK_USERNAME=your_email \
  -e TICKTICK_PASSWORD=your_password \
  -e TICKTICK_DEVICE_ID=your_device_id \
  -s user

使用 -s user （随处可见）， -s project （与团队共享），或 -s local （单个项目）。

配置文件 (~/.claude.json 或 .mcp.json):

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

验证 /mcp 克劳德密码。

Cursor

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目）：

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

保存后重新启动Cursor。

VS Code (Copilot Agent Mode)

需要使用GitHub Copilot的VS代码1.99+。创建 .vscode/mcp.json:

{
  "servers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}
Claude Desktop

编辑配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %AppData%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

退出并重新启动克劳德桌面（Cmd+Q/Alt+F4）。

Cline (VS Code extension)

打开Cline面板>MCP服务器图标>配置，然后添加：

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Dida365（中国）

添加 TICKTICK_HOST=dida365 您的环境变量。这将API调用路由到 api.dida365.com.

节点版本管理器（nvm、fnm等）

如果 node 在MCP客户端中无法解析，请使用完整路径：

"command": "/Users/you/.nvm/versions/node/v22.0.0/bin/node"

使用示例

一旦连接，就自然地说话。以下是根据您的能力组织的示例：

晨间计划

“给我每日总结”

“什么逾期了？”

“我这周要交什么？”

“显示所有高优先级任务”

创建任务

“在我的工作项目中创建一个名为“审查PR#42”的任务，明天到期，优先级高”

将“购买杂货”任务添加到“个人”中，其中包含子任务：牛奶、鸡蛋、面包、黄油

“每周一在我的工作项目中创建一个定期任务‘每周站立笔记’”

“在我的工作项目中创建这些任务：查看设计模型，更新API文档，修复登录错误”

管理任务

“将“发送发票”任务标记为已完成”

“将‘设计审查’移至我的工作项目”

“将‘编写测试’作为‘Ship v2’的子任务”

“我上周完成了哪些任务？”

搜索和筛选

“搜索任何提及‘预算’的任务”

“显示所有中等优先级任务”

“未来3天有哪些任务要完成？”

“显示我的个人项目中有截止日期的所有任务”

项目

“列出我的所有项目”

“使用看板视图创建一个名为“Q2目标”的新项目”

“显示我的工作项目中的所有内容——任务、列、工作”

标签

“显示我的所有标签”

“创建一个名为‘紧急’的红色标签”

“将'bug'标记重命名为'bugfix'”

“将‘todo’标签合并到‘backlog’中”

习惯

“我有什么习惯？”

“检查我今天的‘喝水’习惯”

“养成一种叫做‘阅读’的习惯，目标是每天阅读30页”

“显示我自1月以来的所有入住记录”

专注与生产力

“显示我本月的焦点时间热图”

“我的注意力时间在标签之间是如何分配的？”

“我的生产力统计数据是什么？”

组织

“列出我的项目文件夹”

“创建一个名为“侧项目”的文件夹”

“在我的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 推荐 V2的稳定24个字符十六进制设备id 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；设置a 稳定的 建议使用该值，这样TickTick就不会将每次重启都视为全新的设备。任何24个字符的十六进制字符串都可以使用，或者重用TickTick web客户端已经使用的id（浏览器DevTools→ 应用→ 本地存储→ deviceAnalyticsData.id).

全部52个工具

Project Management (6 tools, V1)
工具 说明
ticktick_get_projects 列出所有项目
ticktick_get_project 按ID获取项目
ticktick_get_project_data 获取包含任务和列的项目
ticktick_create_project 创建项目
ticktick_update_project 更新项目属性
ticktick_delete_project 删除项目
Task Management (6 tools, V1)
工具 说明
ticktick_get_task 按ID获取任务
ticktick_create_task 创建一个包含所有选项的任务
ticktick_update_task 更新任务字段
ticktick_complete_task 将任务标记为已完成
ticktick_delete_task 删除任务
ticktick_batch_create_tasks 一次创建多个任务
Smart Queries & GTD (12 tools, V1)
工具 说明
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 每日完整消化
Tags (5 tools, V2)
工具 说明
ticktick_get_tags 列出所有标签
ticktick_create_tag 创建标签
ticktick_rename_tag 重命名标签
ticktick_delete_tag 删除标签
ticktick_merge_tags 将一个标签合并到另一个标签中
Habits (6 tools, V2)
工具 说明
ticktick_get_habits 列出所有习惯
ticktick_get_habit_sections 获取习惯部分
ticktick_create_habit 养成一个习惯
ticktick_delete_habit 改掉一个习惯
ticktick_checkin_habit 养成习惯
ticktick_get_habit_checkins 查看入住历史记录
Focus / Pomodoro (3 tools, V2)
工具 说明
ticktick_get_focus_heatmap 聚焦时间热图
ticktick_get_focus_distribution 按类别划分的焦点分布
ticktick_get_productivity_stats 生产力得分和统计数据
Completed & Trashed Tasks (2 tools, V2)
工具 说明
ticktick_get_completed_tasks 浏览已完成的任务
ticktick_get_trashed_tasks 查看已删除的任务
Task Organization (2 tools, V2)
工具 说明
ticktick_move_task 将任务移动到其他项目
ticktick_set_task_parent 设置/删除子任务关系
Kanban & Folders (8 tools, V2)
工具 说明
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 将列表移入/移出文件夹
User & Settings (2 tools, V2)
工具 说明
ticktick_get_user_profile 个人资料、电子邮件、时区、订阅
ticktick_get_user_settings 帐户首选项

参考

任务优先级值： 0 =无， 1 =低， 3 =中等， 5 =高

日期格式： yyyy-MM-dd'T'HH:mm:ssZ （例如。 2025-03-15T09:00:00+0000)

重复规则： 标准RRULE格式（例如。 RRULE:FREQ=DAILY;INTERVAL=1)

发展

npm install       # Install dependencies
npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm run clean     # Remove build output

添加工具

  1. 将您的工具添加到相应的文件中 src/tools/
  2. 使用 server.registerTool() 使用Zod输入模式
  3. 它自动对所有MCP客户端可用

建筑

src/
├── index.ts              # Entry point + auth CLI routing
├── config.ts             # Environment variable loader
├── client.ts             # V1 API client (OAuth2)
├── client-v2.ts          # V2 API client (session auth)
├── types.ts              # TypeScript interfaces
├── auth-cli.ts           # Interactive auth wizard
├── auth/oauth.ts         # OAuth2 flow implementation
└── tools/
    ├── project-tools.ts  # Project CRUD (V1)
    ├── task-tools.ts     # Task CRUD (V1)
    ├── smart-tools.ts    # Smart queries & GTD (V1)
    ├── tag-tools.ts      # Tag management (V2)
    ├── habit-tools.ts    # Habit tracking (V2)
    ├── focus-tools.ts    # Focus/Pomodoro stats (V2)
    ├── column-tools.ts   # Kanban columns (V2)
    ├── folder-tools.ts   # Project folders (V2)
    └── v2-task-tools.ts  # Completed tasks, move, user (V2)

两个API客户端都透明地处理身份验证-过期令牌将在401个响应上自动刷新。

故障排除

问题 修复
“缺少必需的环境变量” 运行 node build/index.js auth 或在MCP配置中设置变量
“令牌刷新失败”/401错误 重新运行 node build/index.js auth
服务器未在Claude代码中显示 请使用绝对路径，并检查 /mcp，试试看 claude mcp remove + add
服务器未显示在光标中 重新启动光标，检查输出面板>MCP

贡献

  1. 分叉回购
  2. 创建要素分支
  3. 进行更改并运行 npm run build
  4. 打开拉取请求

许可证

麻省理工学院——见 许可证.

致谢

相关 MCP