TickTick MCP 服务器 -- Claude 的完整 TickTick 集成

License: MIT Version Python Tools Glama

28 个工具。完整 CRUD。智能查询。多条件筛选。批量操作。支持 GTD。兼容滴答清单 (Dida365)。

将 Claude 连接到您的 TickTick 账户，并通过自然对话管理您的整个任务系统——创建任务、跨项目搜索、检查逾期事项、批量创建条目，无需打开应用程序即可保持井井有条。

“有什么逾期的任务？” --> 立即显示所有项目中错过的截止日期。

为什么选择这个？

功能	本服务器	TickTick 官方 MCP	jacepark12
工具数量	28	22	~20
多条件筛选	是（优先级 + 标签 + 日期 + 项目）	是	否
跨项目移动任务	是	是	否
批量完成	是（最多 20 个）	是（最多 20 个）	否
批量更新	是	是	否
已完成任务视图	是	是	否
跨项目搜索	全文搜索	是	是
子任务	是	否	否
GTD 专注视图	是（高优先级 + 到期 + 逾期）	否	部分
支持滴答清单 (Dida365)	是（可配置基础 URL）	否	是
异步 (httpx)	是	N/A	否（同步请求）
Pydantic 验证	是（类型化输入）	N/A	否
MCP 注解	是（只读、破坏性提示）	N/A	否
自托管 / 开源	是	否（托管服务）	是
隐私	100% 本地，仅限您的令牌	经过 TickTick 服务器	100% 本地

Related MCP server: mcp-server-asana

快速入门

前置条件

TickTick 账户
Python 3.10+
Claude Code 或 Claude Desktop

第 1 步 -- 克隆并安装

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

第 2 步 -- 注册 TickTick 开发者应用

前往 developer.ticktick.com
点击 New App 并填写任意名称
将 OAuth Redirect URL 设置为：http://localhost:8080/callback
复制您的 Client ID 和 Client Secret

第 3 步 -- 身份验证

TICKTICK_CLIENT_ID=your_id TICKTICK_CLIENT_SECRET=your_secret .venv/bin/python3 setup_auth.py

这将打开您的浏览器以授权该应用。点击 Allow —— 令牌将保存到 ~/.ticktick_mcp/tokens.json 并自动刷新。

第 4 步 -- 在 Claude Code 中注册

claude mcp add ticktick \
  -e TICKTICK_CLIENT_ID=your_id \
  -e TICKTICK_CLIENT_SECRET=your_secret \
  -- /path/to/ticktick-mcp/.venv/bin/python3 /path/to/ticktick-mcp/server.py

针对 Claude Desktop

添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "ticktick": {
      "type": "stdio",
      "command": "/path/to/ticktick-mcp/.venv/bin/python3",
      "args": ["/path/to/ticktick-mcp/server.py"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_id",
        "TICKTICK_CLIENT_SECRET": "your_secret"
      }
    }
  }
}

第 5 步 -- 添加生产力技能（可选）

mkdir -p ~/.claude/skills/ticktick
cp skills/ticktick/SKILL.md ~/.claude/skills/ticktick/

滴答清单 (Dida365) 支持

对于滴答清单（TickTick 的中文版），请设置以下环境变量：

TICKTICK_BASE_URL=https://api.dida365.com/open/v1
TICKTICK_TOKEN_URL=https://dida365.com/oauth/token

使用示例

您说	发生什么
“提醒我周五给牙医打电话”	创建带有截止日期的任务
“在‘工作’项目中添加‘审查第一季度报告’，高优先级”	在工作项目中创建任务，优先级 5
“有什么逾期的任务？”	显示所有项目中逾期的任务
“我应该关注什么？”	GTD 视图：高优先级 + 今天到期 + 逾期
“搜索关于‘预算’的任何内容”	跨所有项目进行全文搜索
“显示所有高优先级任务”	按优先级=5 跨项目筛选
“本周到期的是什么？”	未来 7 天内到期的任务
“创建任务：买牛奶，给约翰打电话，提交报告”	批量创建 3 个任务
“创建一个名为‘度假计划’的项目”	创建新项目
“在度假任务下添加子任务‘买防晒霜’”	创建子任务
“我完成了牙医任务”	将任务标记为完成
“删除旧的 Sprint 项目”	删除项目及其所有任务

MCP 工具参考

项目 (5 个工具)

工具	描述
`ticktick_list_projects`	列出所有项目及其 ID、名称、颜色
`ticktick_get_project`	获取特定项目的详细信息
`ticktick_get_project_with_tasks`	一次调用获取项目详情 + 所有未完成任务
`ticktick_create_project`	创建新项目（名称、颜色、视图模式）
`ticktick_update_project`	更新项目名称、颜色或视图模式
`ticktick_delete_project`	永久删除项目

任务 -- 基础 CRUD (7 个工具)

工具	描述
`ticktick_list_tasks`	列出特定项目中的所有任务
`ticktick_create_task`	创建任务（标题、截止日期、优先级、项目、标签）
`ticktick_get_task`	获取特定任务的完整详细信息
`ticktick_update_task`	更新标题、内容、日期或优先级
`ticktick_complete_task`	将任务标记为已完成
`ticktick_delete_task`	永久删除任务
`ticktick_create_subtask`	在父任务下创建子任务

任务 -- 智能查询 (7 个工具)

工具	描述
`ticktick_get_all_tasks`	获取所有活跃项目中的所有任务
`ticktick_search_tasks`	跨标题、内容、子任务进行全文搜索
`ticktick_get_tasks_by_priority`	按优先级筛选（无/低/中/高）
`ticktick_get_tasks_due_today`	所有项目中今天到期的任务
`ticktick_get_overdue_tasks`	所有项目中逾期的任务
`ticktick_get_tasks_due_this_week`	未来 7 天内到期的任务
`ticktick_get_tasks_due_in_days`	恰好在 N 天后到期的任务

任务 -- 批量与生产力 (5 个工具)

工具	描述
`ticktick_batch_create_tasks`	一次创建多个任务
`ticktick_batch_update_tasks`	一次更新多个任务
`ticktick_complete_tasks_bulk`	一次将最多 20 个任务标记为完成
`ticktick_move_task`	将任务从一个项目移动到另一个项目
`ticktick_get_focus_tasks`	GTD 专注视图：高优先级 + 今天到期 + 逾期

任务 -- 高级筛选 (2 个工具)

工具	描述
`ticktick_filter_tasks`	多条件筛选：优先级 + 标签 + 日期范围 + 项目 + 状态
`ticktick_get_completed_tasks`	查看项目中的已完成任务

用户 (1 个工具)

工具	描述
`ticktick_get_user_preferences`	获取用户设置（时区、周起始日等）

架构

server.py              # 20 MCP tools, async httpx, Pydantic validation
setup_auth.py          # One-time OAuth 2.0 setup (browser-based)
~/.ticktick_mcp/       # Token storage (auto-refreshed)
skills/ticktick/       # Claude skill for natural task language

设计选择：

全程异步 -- 使用 httpx.AsyncClient 进行非阻塞 API 调用
Pydantic 输入模型 -- 类型安全，经过验证的输入，具有清晰的错误消息
MCP 注解 -- readOnlyHint 和 destructiveHint 用于更安全的工具使用
自动令牌刷新 -- 令牌以 60 秒的缓冲时间透明刷新

故障排除

“Given client ID does not match” -- 请仔细检查 developer.ticktick.com 上的 Client ID。

端口 8080 已被占用 -- 运行 lsof -ti:8080 | xargs kill -9 然后重试。

令牌过期 -- 重新运行 setup_auth.py 以获取新令牌。

Claude 看不到工具 -- 运行 claude mcp list 以验证注册情况。

贡献

欢迎贡献！请先开启一个 issue 来讨论您想要更改的内容。

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Make your changes to server.py
# Test: python3 -c "from server import mcp; print(len(mcp._tool_manager._tools), 'tools')"

链接

许可证

MIT (c) Salen-Project

ticktick-mcp