# 滴答清单 MCP 服务器 [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)  [English Version is Here!](README_en.md) 这是一个基于滴答清单官方API的本地MCP服务，能让用户通过LLM和Agent应用轻松管理待办事项 🔗 **API 文档**: [滴答清单官方 OpenAPI](https://developer.dida365.com/docs#/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 等） ### 安装步骤 ```bash # 克隆项目 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` ```json { "mcpServers": { "ticktick": { "command": ["/path/to/ticktick-mcp-enhanced/.venv/bin/ticktick-mcp"], "enabled": true } } } ``` > **注意**：将 `/path/to/ticktick-mcp-enhanced` 替换为项目的实际绝对路径。Windows 用户请使用双反斜杠 `\\` 或正斜杠 `/`。 ### 🔑 获取 API 凭证 在 [滴答清单开发者中心](https://developer.dida365.com/manage)（国内账号）或 [TickTick Developer Center](https://developer.ticktick.com/manage)（国外账号）注册一个应用。 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` | 按日期范围查询习惯的打卡记录。 | ## 📂 项目结构 ```text 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](LICENSE) 文件 ## 🙏 致谢 - [Model Context Protocol](https://modelcontextprotocol.io/) - [滴答清单 Open API](https://developer.dida365.com/docs#/openapi) - [FastMCP](https://github.com/jlowin/fastmcp)