内容
# TickTick MCP 服务器 - 完整的 TickTick 集成，适用于 Claude
[](LICENSE)
[](https://github.com/Salen-Project/ticktick-mcp/releases)
[](https://python.org)
[](#mcp-tools-reference)
[](https://glama.ai/mcp/servers/Salen-Project/ticktick-mcp)
**28 个工具。完整的 CRUD 操作。智能查询。多条件筛选。批量操作。GTD 支持。兼容 Dida365。**
将 Claude 连接到您的 TickTick 账户，并通过自然对话管理您的整个任务系统 - 创建任务、搜索项目、查看逾期任务、批量创建项目，并保持组织性，无需打开应用程序。
> "什么逾期了？" --> 立即显示所有错过的截止日期，涵盖所有项目。
---
## 为什么选择这个？
| 功能 | 这个服务器 | TickTick 官方 MCP | jacepark12 |
|---|---|---|---|
| **工具** | **28** | 22 | ~20 |
| **多条件筛选** | 是（优先级 + 标签 + 日期 + 项目） | 是 | 否 |
| **任务在项目之间移动** | 是 | 是 | 否 |
| **批量完成** | 是（最多 20 个） | 是（最多 20 个） | 否 |
| **批量更新** | 是 | 是 | 否 |
| **已完成任务视图** | 是 | 是 | 否 |
| **跨项目搜索** | 全文搜索 | 是 | 是 |
| **子任务** | 是 | 否 | 否 |
| **GTD 焦点视图** | 是（高优先级 + 今日截止 + 逾期） | 否 | 部分 |
| **Dida365 支持** | 是（可配置基准 URL） | 否 | 是 |
| **异步（httpx）** | 是 | 不适用 | 否（同步请求） |
| **Pydantic 验证** | 是（类型输入） | 不适用 | 否 |
| **MCP 注释** | 是（只读，破坏性提示） | 不适用 | 否 |
| **自托管 / 开源** | 是 | 否（托管服务） | 是 |
| **隐私** | 100% 本地，您的令牌仅限于本地 | 通过 TickTick 服务器 | 100% 本地 |
---
## 快速开始
### 先决条件
- [TickTick](https://ticktick.com) 账户
- Python 3.10+
- [Claude Code](https://claude.ai/download) 或 Claude 桌面版
### 步骤 1 - 克隆并安装
```bash
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](https://developer.ticktick.com)
2. 点击 **新建应用** 并填写任意名称
3. 将 **OAuth 重定向 URL** 设置为：`http://localhost:8080/callback`
4. 复制您的 **客户端 ID** 和 **客户端密钥**
### 步骤 3 - 身份验证
```bash
TICKTICK_CLIENT_ID=您的 ID TICKTICK_CLIENT_SECRET=您的密钥 .venv/bin/python3 setup_auth.py
```
这将打开您的浏览器以授权应用程序。点击 **允许** - 令牌将保存到 `~/.ticktick_mcp/tokens.json` 并自动刷新。
### 步骤 4 - 在 Claude Code 中注册
```bash
claude mcp add ticktick \
-e TICKTICK_CLIENT_ID=您的 ID \
-e TICKTICK_CLIENT_SECRET=您的密钥 \
-- /path/to/ticktick-mcp/.venv/bin/python3 /path/to/ticktick-mcp/server.py
```
### 对于 Claude 桌面版
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"ticktick": {
"type": "stdio",
"command": "/path/to/ticktick-mcp/.venv/bin/python3",
"args": ["/path/to/ticktick-mcp/server.py"],
"env": {
"TICKTICK_CLIENT_ID": "您的 ID",
"TICKTICK_CLIENT_SECRET": "您的密钥"
}
}
}
}
```
### 步骤 5 - 添加生产力技能（可选）
```bash
mkdir -p ~/.claude/skills/ticktick
cp skills/ticktick/SKILL.md ~/.claude/skills/ticktick/
```
---
## Dida365 支持
对于 Dida365（TickTick 的中文版），请设置以下环境变量：
```bash
TICKTICK_BASE_URL=https://api.dida365.com/open/v1
TICKTICK_TOKEN_URL=https://dida365.com/oauth/token
```
---
## 使用示例
| 您说的话 | 会发生什么 |
|---|---|
| "提醒我在星期五打电话给牙医" | 创建带有截止日期的任务 |
| "将 '查看 Q1 报告' 添加到工作项目中，优先级高" | 任务在工作项目中，优先级为 5 |
| "什么逾期了？" | 显示所有逾期任务，涵盖所有项目 |
| "我应该关注什么？" | GTD 视图：高优先级 + 今日截止 + 逾期 |
| "搜索任何有关 '预算' 的内容" | 全文搜索所有项目 |
| "显示所有高优先级任务" | 按优先级 = 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 工具，异步 httpx，Pydantic 验证
setup_auth.py # 一次性 OAuth 2.0 设置（基于浏览器）
~/.ticktick_mcp/ # 令牌存储（自动刷新）
skills/ticktick/ # Claude 技能，用于自然任务语言
```
**设计选择：**
- **异步操作** - `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` 以验证注册。
---
## 贡献
欢迎贡献！请先打开一个问题讨论您想要更改的内容。
```bash
git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# 对 server.py 进行更改
# 测试：python3 -c "from server import mcp; print(len(mcp._tool_manager._tools), 'tools')"
```
---
## 链接
- [GitHub](https://github.com/Salen-Project/ticktick-mcp)
- [Glama](https://glama.ai/mcp/servers/Salen-Project/ticktick-mcp)
- [报告问题](https://github.com/Salen-Project/ticktick-mcp/issues)
- [TickTick 开发人员门户](https://developer.ticktick.com)
- [TickTick API 文档](https://developer.ticktick.com/api)
---
## 许可证
MIT (c) [Salen-Project](https://github.com/Salen-Project)
