ticktick-mcp-enhanced
Provides tools for managing TickTick tasks, projects, and subtasks, including creating, querying, updating, completing, and deleting tasks, as well as managing projects and subtasks, with OAuth 2.0 authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ticktick-mcp-enhanced Create a task to buy groceries tomorrow at 5pm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
滴答清单 MCP 服务器
这是一个基于滴答清单官方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 优化优先级参数自然语言映射及认证流程。
Related MCP server: TickTick MCP Server
✨ 功能特性
🤖 让 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.jsonWindows:
%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(国外账号)注册一个应用。
点击 "New App"
设置 Redirect URI 为
http://localhost:8000/callback保存你的 Client ID 和 Client Secret
使用方法
重启 LLM 客户端
登录滴答清单
在对话中输入:"帮我登录滴答清单",并提供你的 Client ID 和 Client Secret
AI 会调用
login工具,浏览器自动打开滴答清单授权页在浏览器中点击允许,完成授权
登录状态保存在本地,后续使用无需重复登录
开始使用
查看任务:"查看我今天的任务"
创建任务:"创建一个任务:明天下午3点开会"
查询项目:"查看所有清单"
🧰 可用工具
此 MCP 向你的 LLM 客户端公开以下工具。
类别 | 工具名称 | 功能描述 |
认证 |
| 检查当前的连接和授权状态。 |
| 传入 OAuth 凭据,启动浏览器授权流程并完成登录。 | |
清单 |
| 获取所有清单列表。 |
| 查看特定清单及其中的任务。 | |
| 创建一个新的项目。 | |
| 原地修改项目名称、颜色、视图或类型(支持批量)。 | |
| 删除项目。 | |
任务 |
| 创建任务(支持智能时间识别)。 |
| 修改任务标题、内容、日期或优先级。 | |
| 将任务标记为完成。 | |
| 批量删除任务。 | |
| 为任务添加子任务。 | |
| 在不同项目之间移动任务(支持批量)。 | |
查询 |
| 高级清单查询(支持日期范围、优先级、搜索词)。 |
| 按项目和时间范围查询已完成的任务。 | |
习惯 |
| 获取所有习惯列表。 |
| 按 ID 查看单个习惯。 | |
| 创建习惯(支持批量)。 | |
| 原地修改习惯属性(支持批量)。 | |
| 给习惯打卡,默认今天(支持批量与补打)。 | |
| 按日期范围查询习惯的打卡记录。 |
📂 项目结构
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 文件
🙏 致谢
Available Tools
21 toolscheckin_habitsA
Create or update a habit check-in (mark a habit as done for a given day).
Supports both single check-in and batch. For a single check-in, pass a dictionary directly. For multiple, pass a list of dictionaries.
Important notes on the fields:
date defaults to today when omitted. Internally converted to the API's YYYYMMDD stamp.
value defaults to 1.0. For boolean habits (e.g. "did I run today") keep 1.0; for numeric habits (e.g. "read 30 minutes") set the actual number achieved.
goal defaults to 1.0. Compare value vs goal to know whether the habit was met.
To backfill a missed day, pass the past date explicitly.
Args: checkins: Check-in dictionary or list of dictionaries. Each item must contain: - habit_id (required): ID of the habit to check in - date (optional): Day to check in, YYYY-MM-DD format. Defaults to today. - value (optional): Check-in value, default 1.0 - goal (optional): Check-in goal, default 1.0 - status (optional): Check-in status
Examples: # Check in today for a boolean habit {"habit_id": "habit-1"}
# Numeric habit: read 45 minutes against a 30 minute goal
{"habit_id": "habit-1", "value": 45, "goal": 30}
# Backfill yesterday
{"habit_id": "habit-1", "date": "2026-07-03"}
# Batch
[
{"habit_id": "habit-1"},
{"habit_id": "habit-2", "value": 45, "goal": 30}
]Inputs: checkins (required). Returns: result
complete_tasksA
Mark one or more tasks as complete.
Supports both single task and batch completion. For single task, you can pass a dictionary directly. For multiple tasks, pass a list of dictionaries.
Args: tasks: Task dictionary or list of task dictionaries. Each task must contain: - project_id (required): ID of the project - task_id (required): ID of the task
Examples: # Single task {"project_id": "xyz789", "task_id": "abc123"}
# Multiple tasks
[
{"project_id": "xyz789", "task_id": "abc123"},
{"project_id": "xyz789", "task_id": "def456"},
{"project_id": "abc123", "task_id": "ghi789"}
]Inputs: tasks (required). Returns: result
create_habitsA
Create one or more habits in TickTick.
Supports both single habit and batch creation. For a single habit, pass a dictionary directly. For multiple habits, pass a list of dictionaries.
Args: habits: Habit dictionary or list of habit dictionaries. Each habit must contain: - name (required): Habit name (max 1000 characters) - color (optional): Hex color code, e.g. "#4D8CF5" - type (optional): Habit type, e.g. "Boolean" - goal (optional): Numeric goal, default 1.0 - step (optional): Numeric step value - unit (optional): Unit of the goal, e.g. "Count" - repeat_rule (optional): Recurrence rule, e.g. "RRULE:FREQ=DAILY;INTERVAL=1" - reminders (optional): List of reminder trigger strings - encouragement (optional): Encouragement message - status (optional): Habit status
Examples: # Single boolean habit, repeated daily { "name": "Read", "color": "#4D8CF5", "type": "Boolean", "goal": 1.0, "repeat_rule": "RRULE:FREQ=DAILY;INTERVAL=1" }
# Multiple habits
[
{"name": "Read", "repeat_rule": "RRULE:FREQ=DAILY;INTERVAL=1"},
{"name": "Exercise", "repeat_rule": "RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"}
]Inputs: habits (required). Returns: result
create_projectA
Create a new project in TickTick.
Args: name: Project name color: Color code (hex format) (optional) view_mode: View mode - one of list, kanban, or timeline (optional)
Inputs: name (required), color, view_mode. Returns: result
create_subtasksA
Create one or more subtasks for parent tasks. For single subtask, you can pass a dictionary directly. For multiple subtasks, pass a list of dictionaries.
Args: subtasks: Subtask dictionary or list of subtask dictionaries. Each subtask must contain: - subtask_title (required): Title of the subtask - parent_task_id (required): ID of the parent task - project_id (required): ID of the project (must be same for both parent and subtask) - content (optional): Content/description for the subtask - priority (optional): Priority level - "none", "low", "medium", or "high" (case-insensitive)
Examples: # Single subtask {"subtask_title": "Subtask 1", "parent_task_id": "abc123", "project_id": "xyz789"}
# Multiple subtasks
[
{"subtask_title": "Subtask 1", "parent_task_id": "abc123", "project_id": "xyz789", "priority": "medium"},
{"subtask_title": "Subtask 2", "parent_task_id": "abc123", "project_id": "xyz789", "content": "Details"}
]Inputs: subtasks (required). Returns: result
create_tasksA
Create one or more tasks in TickTick.
Supports both single task and batch creation. For single task, you can pass a dictionary directly. For multiple tasks, pass a list of dictionaries.
Args: tasks: Task dictionary or list of task dictionaries. Each task must contain: - title (required): Task Name - project_id (required): ID of the project for the task - content (optional): Task description - desc (optional): Description of checklist - start_date (optional): ISO datetime WITH timezone offset (e.g., 2025-12-16T08:00:00+0000) - due_date (optional): ISO datetime WITH timezone offset - time_zone (required): IANA timezone name (e.g. "Asia/Shanghai") - priority (optional): Priority level - "none", "low", "medium", or "high" - repeat_flag (optional): Recurring rules (e.g., "RRULE:FREQ=DAILY;INTERVAL=1") - items (optional): List of subtask dictionaries - reminders (optional): List of iCal TRIGGER strings. Without this, NO alarm fires even if due_date is set. Examples: ["TRIGGER:PT0S"] → at due time ["TRIGGER:-PT15M"] → 15 minutes before ["TRIGGER:-PT1H"] → 1 hour before ["TRIGGER:-P1D"] → 1 day before ["TRIGGER:-PT15M","TRIGGER:PT0S"] → 15 min before AND at due
Examples: # Single task with Beijing timezone, ring at due time { "title": "Buy milk", "project_id": "1234ABC", "content": "2% organic", "due_date": "2025-12-16T16:00:00+08:00", "time_zone": "Asia/Shanghai", "priority": "medium", "reminders": ["TRIGGER:PT0S"] }
# Multiple tasks (one timed, one all-day by omitting due_date)
[
{
"title": "Example A",
"project_id": "1234ABC",
"desc": "Timed task",
"due_date": "2025-07-19T10:00:00+0000",
"time_zone": "Asia/Shanghai",
"priority": "high"
},
{
"title": "Example B",
"project_id": "1234XYZ",
"content": "All-day task (no due_date means all-day)"
}
]Inputs: tasks (required). Returns: result
delete_projectsA
Delete one or more projects.
Supports both single project and batch deletion. For single project, you can pass a project ID string directly. For multiple projects, pass a list of project IDs.
Args: projects: Project ID string or list of project ID strings
Examples: # Single project "abc123"
# Multiple projects
["abc123", "def456", "ghi789"]Inputs: projects (required). Returns: result
delete_tasksA
Delete one or more tasks.
Supports both single task and batch deletion. For single task, you can pass a dictionary directly. For multiple tasks, pass a list of dictionaries.
Args: tasks: Task dictionary or list of task dictionaries. Each task must contain: - project_id (required): ID of the project - task_id (required): ID of the task
Examples: # Single task {"project_id": "xyz789", "task_id": "abc123"}
# Multiple tasks
[
{"project_id": "xyz789", "task_id": "abc123"},
{"project_id": "xyz789", "task_id": "def456"},
{"project_id": "abc123", "task_id": "ghi789"}
]Inputs: tasks (required). Returns: result
get_all_habitsA
List all of the user's habits.
No parameters. Returns complete habit objects (including each habit's ID) so you can act on them directly, for example to create a check-in afterwards.
Example: get_all_habits()
Inputs: no named parameters. Returns: result
get_all_projectsA
Get all projects from TickTick.
Note: This does not include the special "Inbox" project. To get inbox information and tasks, use get_project_info(project_id="inbox").
Inputs: no named parameters. Returns: result
get_completed_tasksA
List tasks that have been completed within a given set of projects and time range.
All parameters are optional, but at least one is recommended to narrow the results. Returns complete task objects (id, projectId, completedTime, ...) so you can act on them directly without a second lookup.
Args: project_ids: List of project IDs to search across (use "inbox" for the inbox). start_date: ISO datetime WITH timezone offset, inclusive lower bound on completedTime (e.g., "2026-03-01T00:00:00+0800"). end_date: ISO datetime WITH timezone offset, inclusive upper bound on completedTime.
Examples: # Tasks completed in one project during March 2026 {"project_ids": ["abc123"], "start_date": "2026-03-01T00:00:00+0800", "end_date": "2026-03-31T23:59:59+0800"}
# All completed tasks across every project (no filters)
{}Inputs: end_date, start_date, project_ids. Returns: result
get_habitA
Get a single habit by its ID.
Args: habit_id: ID of the habit
Example: get_habit("habit-1")
Inputs: habit_id (required). Returns: result
get_habit_checkinsA
Get habit check-in records within a date range.
Returns complete check-in objects so you can analyze streaks, completion rates or find missed days without a second lookup.
Args: habit_ids: A single habit ID or a list of habit IDs from_date: Start date, YYYYMMDD integer (e.g. 20260401) to_date: End date, YYYYMMDD integer (e.g. 20260407)
Example: # One week of check-ins for two habits {"habit_ids": ["habit-1", "habit-2"], "from_date": 20260401, "to_date": 20260407}
Inputs: to_date (required), from_date (required), habit_ids (required). Returns: result
get_project_infoA
Get comprehensive information about a project, including its details and all tasks.
This tool provides a complete view of a project in one call, showing both the project metadata (name, color, view mode, etc.) and all tasks within it.
Args: project_id: ID of the project, or "inbox" to get inbox information
Returns: A formatted string containing: - Project basic information (name, ID, color, etc.) - List of all tasks in the project with their details
Examples: - get_project_info("abc123") → Get project info and tasks - get_project_info("inbox") → Get inbox info and tasks
Inputs: project_id (required). Returns: result
loginA
Log in to TickTick by providing OAuth credentials.
Ask the user for all four parameters. They can be found on the developer console app settings page:
China / Dida365: https://developer.dida365.com/manage
Global / TickTick: https://developer.ticktick.com/manage
Args: client_id (required): OAuth application Client ID, shown on the app page. client_secret (required): OAuth application Client Secret, shown on the app page. account_type (optional, default "china"): "china" for Dida365 or "global" for TickTick international. Use the default unless the user explicitly says they use the international version (ticktick.com). redirect_uri (optional, default "http://localhost:8000/callback"): the callback URL configured in the developer console. Use the default unless the user explicitly states a different value. Never invent a URL — if the user does not provide one, use the default.
After calling this tool, a browser window opens automatically for the user to authorize. The tool blocks until authorization completes or times out (up to 120 seconds).
Inputs: client_id (required), client_secret (required), account_type, redirect_uri. Returns: result
move_tasksA
Move one or more tasks from their current project to a different project.
Args: moves: Move dictionary, or list of dictionaries. Each item must contain: - from_project_id (required): ID of the source project - to_project_id (required): ID of the destination project - task_id (required): ID of the task to move
Examples: # Move a single task {"from_project_id": "abc123", "to_project_id": "def456", "task_id": "task789"}
# Move multiple tasks
[
{"from_project_id": "abc123", "to_project_id": "def456", "task_id": "task1"},
{"from_project_id": "abc123", "to_project_id": "def456", "task_id": "task2"}
]Inputs: moves (required). Returns: result
query_tasksA
Unified task query tool with flexible multi-dimensional filtering.
All parameters are optional. When no filters are provided, returns all tasks. Multiple filters can be combined - tasks must match ALL specified criteria (AND logic).
Args: task_id: Get a specific task by ID. When combined with project_id, uses direct API call (most efficient). When used alone, searches all tasks for matching ID. Can be combined with other filters to verify task properties. project_id: Limit search to specific project (use "inbox" for inbox tasks). When combined with task_id, enables direct API lookup. date_filter: Filter by date - one of: - "today": Tasks due today - "tomorrow": Tasks due tomorrow - "overdue": Overdue tasks - "next_7_days": Tasks due within the next 7 days - "custom": Tasks due in a specific number of days (requires custom_days) custom_days: Number of days from today (only for date_filter="custom") e.g., 0 for today, 1 for tomorrow, 3 for 3 days from now priority: Filter by priority level: "none", "low", "medium","high"(case-insensitive): search_term: Search keyword in title, content, or subtask titles (case-insensitive)
Examples: query_tasks() → All tasks query_tasks(task_id="abc123", project_id="xyz789") → Get specific task query_tasks(task_id="abc123") → Find task by ID across all projects query_tasks(date_filter="today") → Tasks due today query_tasks(priority="high") → High priority tasks query_tasks(date_filter="today", priority="high") → High priority tasks due today query_tasks(search_term="meeting") → Tasks containing "meeting"
Inputs: task_id, priority, project_id, custom_days, +2 more. Returns: result
ticktick_statusA
Check the current connection status with TickTick. Returns whether the server is configured, authenticated, and ready to use.
Inputs: no named parameters. Returns: result
update_habitsA
Update one or more existing habits in place.
Only the fields you provide are changed; omitted fields keep their current value.
Args: habits: Habit update dictionary, or list of dictionaries. Each item must contain: - habit_id (required): ID of the habit to update - name (optional): New habit name - color (optional): New color (hex code) - type (optional): New habit type - goal (optional): New numeric goal - step (optional): New step value - unit (optional): New unit - repeat_rule (optional): New recurrence rule - reminders (optional): New reminder triggers - encouragement (optional): New encouragement message - status (optional): New status
Examples: # Rename a single habit {"habit_id": "habit-1", "name": "Read more"}
# Update goal and repeat rule for two habits
[
{"habit_id": "habit-1", "goal": 2.0},
{"habit_id": "habit-2", "repeat_rule": "RRULE:FREQ=DAILY;INTERVAL=2"}
]Inputs: habits (required). Returns: result
update_projectsA
Update one or more existing projects in place (without deleting them).
Only the fields you provide are changed; omitted fields keep their current value. Use this instead of delete-then-recreate to avoid losing the tasks inside a project.
Args: projects: Project update dictionary, or list of dictionaries. Each item must contain: - project_id (required): ID of the project to update - name (optional): New project name - color (optional): New color (hex code, e.g. "#F18181") - view_mode (optional): One of "list", "kanban", "timeline" - kind (optional): Project type - "TASK" or "NOTE"
Examples: # Rename a single project {"project_id": "abc123", "name": "Archived Work"}
# Switch several projects to kanban view
[
{"project_id": "abc123", "view_mode": "kanban"},
{"project_id": "def456", "view_mode": "kanban"}
]Inputs: projects (required). Returns: result
update_tasksA
Update one or more existing tasks in TickTick.
Supports both single task and batch updates. For single task, you can pass a dictionary directly. For multiple tasks, pass a list of dictionaries.
Args: tasks: Task dictionary or list of task dictionaries. Each task must contain: - task_id (required): ID of the task to update - project_id (required): ID of the project the task belongs to - title (optional): task title - content (optional): task description/content - desc (optional): description of checklist - start_date (optional): ISO datetime WITH timezone offset - due_date (optional): ISO datetime WITH timezone offset; omit to make an all-day task - time_zone (optional): IANA timezone name (e.g., "Asia/Shanghai", "America/New_York") - priority (optional): priority level - "none", "low", "medium", or "high" - repeat_flag (optional): Recurring rules - items (optional): List of subtask dictionaries - reminders (optional): List of iCal TRIGGER strings (e.g., ["TRIGGER:PT0S"] = at due, ["TRIGGER:-PT15M"] = 15 min before). Pass [] to clear all reminders.
Examples: # Single task update (set due date with timezone) { "task_id": "abc123", "project_id": "xyz789", "title": "Updated title", "due_date": "2025-12-31T15:00:00+08:00", "time_zone": "Asia/Shanghai", "priority": "high" }
Inputs: tasks (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target a distinct resource and action (create/update/delete/query per entity), and descriptions are detailed enough to separate them. Minor overlap exists between get_project_info and query_tasks (both return tasks within a project) and between create_tasks' items parameter and the dedicated create_subtasks tool.
The overwhelming majority follow a clear verb_noun pattern (create_tasks, update_projects, get_all_habits, checkin_habits), making the convention predictable. Minor deviations: ticktick_status and login break the pattern by being noun-style and bare-verb respectively.
At 21 tools, this sits in the heavy range, though each tool maps to a genuine operation across three resource types (projects, tasks, habits) plus auth. The count is defensible for a full-featured task manager, but an agent faces a large surface to navigate.
Projects and tasks have thorough lifecycle coverage (create/read/update/delete/complete/move/query), and habits have get/create/update/checkin coverage. However, there is no delete_habits tool, leaving habits without a deletion path, and subtasks only support creation with no dedicated update/delete operations.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Unofficial community ClickUp MCP via personal API token. Not affiliated with ClickUp.
Create, list, and complete todo items through MCP.
Related MCP Servers
- AlicenseCqualityDmaintenanceAgent-friendly CLI and MCP server for TickTick and Dida365 task management APIs, enabling project and task management with stable JSON output and OAuth authentication.171MIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with TickTick task management system through MCP, allowing users to view, create, update, complete, and delete tasks and projects via natural language.-
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that connects AI assistants to your TickTick tasks, enabling task management through natural language.81MIT
- AlicenseBqualityFmaintenanceMCP server that enables AI agents to manage Dida365/TickTick tasks, projects, tags, and habits through natural language, with full CRUD, search, and advanced V2 capabilities.192MIT