Skip to main content
Glama

滴答清单 MCP 服务器

Python 3.10+ License: MIT PRs Welcome

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 优化优先级参数自然语言映射及认证流程。

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.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 文件

🙏 致谢

Available Tools

21 tools
checkin_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:

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

    A3.9/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers