TickTick MCP Server

任务管理是现代工作和生活的核心。TickTick 以其跨平台、功能丰富的特点，成为许多人管理待办事项的首选工具。但即便如此，在编写代码、撰写文档或与 AI 深度协作时，频繁切换到 TickTick 去创建、查询或更新任务，依然会打断宝贵的心流。TickTick MCP Server 的出现，正是为了消除这种切换。它通过模型上下文协议（MCP），将 TickTick 的任务管理能力无缝融入你的 AI 助手，让你在对话中就能完成所有任务操作，真正实现“思考即管理”。

项目基本信息

一、项目介绍

TickTick MCP Server 是一个用 Python 开发的 MCP 服务器，它作为桥梁，将 TickTick 开放 API 的强大功能以标准化 MCP 工具的形式，暴露给 Claude Desktop 等支持 MCP 的 AI 客户端。

核心工具集

该服务器提供了 11 个 MCP 工具，覆盖了任务和项目管理的主要操作：

• 项目浏览：get_projects（列出所有项目）、get_project（获取特定项目详情）、get_project_tasks（列出项目中所有任务）
• 任务操作：get_task（查看任务详情）、create_task（创建新任务）、update_task（更新任务）、complete_task（标记完成）、delete_task（删除任务）
• 项目管理：create_project（创建新项目）、delete_project（删除项目）

双重平台支持

该项目不仅支持国际版 TickTick，还专门适配了中国版 滴答清单（Dida365）。通过在环境变量中配置不同的 API 端点，同一套代码可以无缝切换两个平台。

二、核心优势

OAuth2 安全认证，一键完成

项目实现了完整的 OAuth2 授权流程，并做了极大的简化。通过 uv run -m ticktick_mcp.cli auth 命令，它会引导你完成从注册应用到获取令牌的全部过程，自动打开浏览器进行授权，并自动保存和刷新令牌。这意味着你不需要手动处理复杂的 API 密钥和令牌管理。

全面的任务操作能力

不仅支持基本的增删改查，还支持设置任务优先级、开始/截止日期、任务内容等详细参数。通过自然语言，你可以创建带有完整属性的任务：“在我的工作项目中创建一个名为‘完成 MCP 服务器文档’的新任务，优先级为高，截止日期为本周五”。

与 Claude Desktop 深度集成

项目文档提供了清晰的 Claude Desktop 配置方法，配置完成后，你可以在对话中直接看到 TickTick 的工具列表，通过自然语言指令即可完成所有操作。

MIT 开源协议

使用 MIT 协议授权，对个人和商业使用都非常友好，可以自由集成和修改。

三、适用场景

对话式任务管理

在与 AI 讨论工作、学习计划时，随时将结论转化为任务：“帮我在 TickTick 中创建一个任务，提醒我明天下午 3 点参加项目评审会议。”

每日工作流整合

早上开始工作时，让 AI 帮你梳理今日待办：“列出我所有 TickTick 项目中今天截止的任务，按优先级排序。”

会议纪要转任务

会议结束后，将讨论产生的行动项逐一录入：“在‘市场推广’项目中创建三个任务：1. 撰写推广文案，2. 设计宣传海报，3. 联系合作媒体。”

自动化任务工作流

结合其他 MCP 工具，可以构建更复杂的自动化流程。例如：当代码仓库的 Issue 关闭时，自动在 TickTick 中完成对应任务。

四、安装教程

环境要求

安装步骤

第一步：克隆仓库

git clone https://github.com/jacepark12/ticktick-mcp.git
cd ticktick-mcp

第二步：使用 uv 安装

# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv

# 激活虚拟环境
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# 安装依赖
uv pip install -e .

第三步：注册 TickTick 应用

1. 前往 TickTick 开发者中心注册一个应用。
2. 重要：将重定向 URI 设置为 http://localhost:8000/callback。
3. 记下获得的客户端 ID 和客户端密钥。

第四步：进行 OAuth2 身份验证

uv run -m ticktick_mcp.cli auth

按照提示输入客户端 ID 和客户端密钥，浏览器将自动打开，引导你完成授权。完成后，访问令牌将自动保存到 .env 文件中，无需手动管理。

第五步：测试配置

uv run test_server.py

如果输出正常，说明凭证配置成功。

配置 Claude Desktop

编辑 Claude Desktop 的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置，务必使用绝对路径：

{
   "mcpServers": {
      "ticktick": {
         "command": "<uv 的绝对路径>",
         "args": ["run", "--directory", "<ticktick-mcp 目录的绝对路径>", "-m", "ticktick_mcp.cli", "run"]
      }
   }
}

提示：在终端中运行 which uv 可获取 uv 的绝对路径。

保存配置文件后，完全退出并重启 Claude Desktop。连接成功后，Claude 中会显示 TickTick MCP 服务器工具（由工具图标标识）。

使用滴答清单（Dida365）？

如果你使用的是中国版滴答清单，在 .env 文件中添加以下环境变量：

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

其余步骤与 TickTick 相同。

五、使用示例

示例一：查看所有项目

用户：显示我所有的 TickTick 项目

AI 调用 get_projects 工具，返回你的项目列表。

示例二：创建任务

用户：在我的“工作”项目中创建一个名为“准备季度汇报 PPT”的任务，优先级设为高，截止日期为本周五。

AI 调用 create_task 工具，传入项目 ID、任务标题、优先级和截止日期，完成创建。

示例三：查看即将截止的任务

用户：列出我在 TickTick 中所有明天截止的任务。

AI 调用 get_projects 获取所有项目，然后遍历每个项目调用 get_project_tasks，筛选出明日截止的任务并汇总展示。

示例四：批量标记完成

用户：把“工作”项目中所有已完成的任务标记为完成状态。

AI 先调用 get_project_tasks 获取任务列表，然后对需要完成的任务逐一调用 complete_task。

六、常见问题

问：配置完成后，Claude 提示找不到工具怎么办？

答：请按以下步骤排查：

1. 检查路径：确保 claude_desktop_config.json 中 command 和 --directory 使用绝对路径，且路径中不包含空格或特殊字符。
2. 检查虚拟环境：确保已运行 uv venv 并激活虚拟环境。
3. 检查认证状态：重新运行 uv run -m ticktick_mcp.cli auth 确认令牌有效。
4. 查看 Claude 日志：Claude Desktop 通常会输出 MCP 服务器的连接错误信息。

问：身份验证的令牌会过期吗？

答：TickTick MCP Server 实现了自动令牌刷新机制。初始授权后，服务器会自动处理令牌的刷新，除非你撤销访问权限或删除 .env 文件，否则无需重新进行身份验证。

问：TickTick 和滴答清单（Dida365）有什么区别？

答：滴答清单是 TickTick 的中国版本，两者功能相似但 API 端点不同。如果你使用滴答清单，需要在 .env 文件中配置 TICKTICK_BASE_URL 等环境变量，将其指向 api.dida365.com。

问：可以同时管理多个 TickTick 账户吗？

答：当前配置指向单个 .env 文件，存储一套令牌。如需管理多个账户，可以创建多个项目目录，分别配置各自的认证信息，并在 Claude Desktop 配置中添加多个 MCP 服务器条目。

七、总结

TickTick MCP Server 是任务管理与 AI 协作相结合的典范。它通过标准化的 MCP 协议和简化的 OAuth2 认证流程，将 TickTick 的强大功能无缝注入你的 AI 工作流。对于重度 TickTick 用户和 AI 辅助工作流的实践者来说，花十分钟完成配置，你将获得一个“不会遗忘、随叫随到”的任务管理助手。它让记录待办、规划项目不再是打断思维的额外操作，而成为对话中自然流动的一部分。