滴答清单 MCP 服务器

Python 3.10+ License: MIT

English Version is Here!

这是一个基于滴答清单官方API的本地MCP服务，能让用户通过LLM和Agent应用轻松管理待办事项

🔗 API 文档: 滴答清单官方 OpenAPI

---

📢 Update

• 2026-07-04 新增任务移动、已完成任务查询、项目更新、习惯管理模块 — 共 9 个新工具（move_tasks、get_completed_tasks、update_projects，以及习惯模块的 get_all_habits、get_habit、create_habits、update_habits、checkin_habits、get_habit_checkins）。
• 2026-07-02 重构认证系统 — 移除环境变量配置，改为运行时 login 工具直接传入 OAuth 凭据，支持中国版/国际版一键切换。
• 2026-05-12 提取工具描述 — 将所有工具的 Prompt 提取为独立 .txt 文件，便于维护和修改。
• 2026-05-09 新增提醒参数 — 创建和更新任务时支持 reminders，可设置到期前推送提醒。
• 2026-01-29 项目结构重构 — 迁移到 src 目录布局，代码组织更规范。
• 2026-01-17 日志系统升级 — 改为基于会话的纯文件日志，交互追踪更清晰。
• 2026-01-12 全面重构 — 实现无缝本地 OAuth 回调认证、统一日志追踪、移除 python-dotenv 依赖。
• 2025-12-07 修复时区处理问题。
• 2025-10-17 优化优先级参数自然语言映射及认证流程。

✨ 功能特性

• 🤖 让 AI Agent 管理你的任务：通过自然语言指令创建、查询、更新和完成任务
• 🔑 运行时 OAuth 认证：通过 login 工具直接传入凭据，浏览器自动打开授权页面，无需配置环境变量
• 📅 任务管理：支持创建任务、项目、子任务，以及复杂的查询功能
• 🔍 高级查询：按日期范围、优先级、关键词等多维度筛选任务

🚀 安装与使用

前置条件

• Python 版本：3.10 或更高
• LLM 客户端（如 Claude Desktop、OpenCode 等）

安装步骤

# 克隆项目
git clone https://github.com/Code-MonkeyZhang/ticktick-mcp-enhanced.git
cd ticktick-mcp-enhanced

# 创建虚拟环境并安装
uv venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

uv pip install -e .

配置 LLM 客户端

在 Claude Desktop 或其他 LLM 应用的配置文件中添加：

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

{
  "mcpServers": {
    "ticktick": {
      "command": ["/path/to/ticktick-mcp-enhanced/.venv/bin/ticktick-mcp"],
      "enabled": true
    }
  }
}

注意：将 /path/to/ticktick-mcp-enhanced 替换为项目的实际绝对路径。Windows 用户请使用双反斜杠 \\ 或正斜杠 /。

🔑 获取 API 凭证

在 滴答清单开发者中心（国内账号）或 TickTick Developer Center（国外账号）注册一个应用。

1. 点击 "New App"
2. 设置 Redirect URI 为 http://localhost:8000/callback
3. 保存你的 Client ID 和 Client Secret

使用方法

1. 重启 LLM 客户端
2. 登录滴答清单
   • 在对话中输入："帮我登录滴答清单"，并提供你的 Client ID 和 Client Secret
   • AI 会调用 login 工具，浏览器自动打开滴答清单授权页
   • 在浏览器中点击允许，完成授权
   • 登录状态保存在本地，后续使用无需重复登录
3. 开始使用
   • 查看任务："查看我今天的任务"
   • 创建任务："创建一个任务：明天下午3点开会"
   • 查询项目："查看所有清单"

🧰 可用工具

此 MCP 向你的 LLM 客户端公开以下工具。

类别	工具名称	功能描述
认证	ticktick_status	检查当前的连接和授权状态。
	login	传入 OAuth 凭据，启动浏览器授权流程并完成登录。
清单	get_all_projects	获取所有清单列表。
	get_project_info	查看特定清单及其中的任务。
	create_project	创建一个新的项目。
	update_projects	原地修改项目名称、颜色、视图或类型（支持批量）。
	delete_projects	删除项目。
任务	create_tasks	创建任务（支持智能时间识别）。
	update_tasks	修改任务标题、内容、日期或优先级。
	complete_tasks	将任务标记为完成。
	delete_tasks	批量删除任务。
	create_subtasks	为任务添加子任务。
	move_tasks	在不同项目之间移动任务（支持批量）。
查询	query_tasks	高级清单查询（支持日期范围、优先级、搜索词）。
	get_completed_tasks	按项目和时间范围查询已完成的任务。
习惯	get_all_habits	获取所有习惯列表。
	get_habit	按 ID 查看单个习惯。
	create_habits	创建习惯（支持批量）。
	update_habits	原地修改习惯属性（支持批量）。
	checkin_habits	给习惯打卡，默认今天（支持批量与补打）。
	get_habit_checkins	按日期范围查询习惯的打卡记录。

📂 项目结构

ticktick-mcp-enhanced/
├── src/
│   └── ticktick_mcp/
│       ├── __init__.py          # 包入口
│       ├── server.py            # MCP 服务入口
│       ├── auth.py              # OAuth 逻辑与回调服务器
│       ├── client_manager.py    # 客户端管理
│       ├── log.py               # 日志配置
│       ├── ticktick_client.py   # TickTick API 客户端
│       ├── tools/               # 各类工具实现
│       │   ├── project_tools.py # 清单工具
│       │   ├── task_tools.py    # 任务工具
│       │   ├── query_tools.py   # 查询工具
│       │   ├── habit_tools.py   # 习惯工具
│       │   └── prompts/         # 工具描述 (.txt)
│       └── utils/               # 格式化与校验工具
├── pyproject.toml              # 项目配置与依赖
└── README.md                  # 本文档

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

• Model Context Protocol
• 滴答清单 Open API
• FastMCP