Tick Tick Mcp

TickTick MCP 服务——适用于 Claude 的完整 TickTick 集成

28 个工具。完整的 CRUD。智能查询。多条件筛选。批量操作。支持 GTD。兼容 Dida365。

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

“哪些事项已逾期？” --> 立即显示所有项目中错过截止日期的事项。

---

为什么选择它？

功能	本服务	TickTick 官方 MCP	jacepark12
工具	28	22	~20
多条件筛选	支持（优先级 + 标签 + 日期 + 项目）	支持	不支持
在项目间移动任务	支持	支持	不支持
批量完成	支持（最多 20 项）	支持（最多 20 项）	不支持
批量更新	支持	支持	不支持
已完成任务视图	支持	支持	不支持
跨项目搜索	全文搜索	支持	支持
子任务	支持	不支持	不支持
GTD 专注视图	支持（高优先级 + 到期 + 逾期）	不支持	部分支持
Dida365 支持	支持（可配置基础 URL）	不支持	支持
异步（httpx）	支持	不适用	不支持（同步请求）
Pydantic 验证	支持（类型化输入）	不适用	不支持
MCP 注解	支持（readOnly、破坏性操作提示）	不适用	不支持
可自托管 / 开源	支持	不支持（托管服务）	支持
隐私	100% 本地，仅使用你的令牌	通过 TickTick 服务端处理	100% 本地

---

快速开始

前提条件

• 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 开发者应用

1. 前往 developer.ticktick.com
2. 点击 New App 并填写任意名称
3. 将 OAuth Redirect URL 设置为：http://localhost:8080/callback
4. 复制你的 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 支持

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

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

---

使用示例

你说	执行结果
“提醒我周五给牙医打电话”	创建带截止日期的任务
“在 Work 中添加‘审核 Q1 报告’，设为高优先级”	在 Work 项目中创建任务，优先级为 5
“哪些事项已逾期？”	显示所有项目中已逾期的任务
“我应该专注做什么？”	GTD 视图：高优先级 + 今天到期 + 逾期
“搜索所有与‘预算’有关的内容”	跨所有项目进行全文搜索
“显示所有高优先级任务”	跨项目按 priority=5 筛选
“本周有哪些事项到期？”	显示未来 7 天内到期的任务
“创建任务：买牛奶、给 John 打电话、提交报告”	批量创建 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 秒缓冲时间

---

故障排除

“给定的客户端 ID 不匹配” -- 请仔细核对 developer.ticktick.com 上的客户端 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')"

---

链接

• GitHub
• Glama
• 报告问题
• TickTick 开发者门户
• TickTick API 文档

---

许可证

MIT (c) Salen-Project