TickTick MCP Server

TickTick MCP 服务

TickTick API 的 MCP 服务，支持任务管理、项目组织、习惯追踪等功能。

功能

• ✅ 任务管理：创建、读取、更新和删除任务，支持所有可用属性
• 📊 项目管理：创建、读取、更新和删除项目，并支持自定义视图
• 📋 子任务支持：全面支持管理父任务中的子任务
• 🔄 完整的任务控制：设置优先级、截止日期、提醒和重复规则
• 🔐 OAuth 身份验证：完整实现 OAuth2，确保 API 访问安全
• ⚠️ 全面的错误处理：针对常见问题提供清晰的错误消息

工具

1. get_task_by_ids

   • 根据项目 ID 和任务 ID 获取指定任务
   • 输入：
     • projectId（string）：项目标识符
     • taskId（string）：任务标识符
   • 返回：符合 TickTickTaskSchema 的任务对象

2. create_task

   • 在项目中创建新任务
   • 输入：
     • title（string）：任务标题
     • projectId（string）：项目 ID
     • content（可选 string）：任务内容
     • desc（可选 string）：任务描述
     • isAllDay（可选 boolean）：是否为全天任务
     • startDate（可选 string）：任务开始日期，格式为 "yyyy-MM-dd'T'HH:mm:ssZ"
     • dueDate（可选 string）：任务截止日期，格式为 "yyyy-MM-dd'T'HH:mm:ssZ"
     • timeZone（可选 string）：任务时区（例如："America/Los_Angeles"）
     • reminders（可选 string[]）：iCalendar 格式的提醒触发器列表
     • repeatFlag（可选 string）：iCalendar 格式的任务重复标记
     • priority（可选 number）：任务优先级（无：0，低：1，中：3，高：5）
     • sortOrder（可选 string）：任务排序顺序
     • items（可选 array）：子任务列表，包含：
       • title（string）：子任务标题
       • startDate（可选 string）：子任务日期，格式为 "yyyy-MM-dd'T'HH:mm:ssZ"
       • isAllDay（可选 boolean）：子任务是否为全天任务
       • sortOrder（可选 number）：子任务排序顺序
       • timeZone（可选 string）：子任务时区
       • status（可选 number）：完成状态（正常：0，已完成：1）
       • completedTime（可选 string）：完成时间，格式为 "yyyy-MM-dd'T'HH:mm:ssZ"
   • 返回：符合 TickTickTaskSchema 的已创建任务对象

3. update_task

   • 更新现有任务
   • 输入：
     • taskId（string）：任务标识符 - 路径
     • id（string）：任务标识符 - 请求体
     • projectId（string）：项目 ID
     • create_task 中的所有可选字段
   • 返回：符合 TickTickTaskSchema 的已更新任务对象

4. complete_task

   • 将任务标记为已完成
   • 输入：
     • taskId（string）：任务标识符
     • projectId（string）：项目标识符
   • 返回：void

5. delete_task

   • 从项目中删除任务
   • 输入：
     • taskId（string）：任务标识符
     • projectId（string）：项目标识符
   • 返回：void

6. get_user_projects

   • 获取已验证身份用户的所有项目
   • 输入：无
   • 返回：符合 TickTickProjectSchema 的项目对象数组

7. get_project_by_id

   • 根据 ID 获取指定项目
   • 输入：
     • projectId（string）：项目标识符
   • 返回：符合 TickTickProjectSchema 的项目对象

8. get_project_with_data

   • 获取项目详情以及任务和列
   • 输入：
     • projectId（string）：项目标识符
   • 返回：包含以下内容的对象：
     • project：符合 TickTickProjectSchema 的项目对象
     • tasks：符合 TickTickTaskSchema 的任务对象数组
     • columns：可选的列对象数组，包含：
       • id（可选 string）
       • projectId（可选 string）
       • name（可选 string）
       • sortOrder（可选 number）

9. create_project

   • 创建新项目
   • 输入：
     • name（字符串）：项目名称
     • color（可选字符串）：项目颜色（默认值：'#4772FA'）
     • viewMode（可选字符串）：视图模式（'list'、'kanban'、'timeline'）（默认值：'list'）
     • kind（可选字符串）：项目类型（'TASK'、'NOTE'）（默认值：'TASK'）
   • 返回：符合 TickTickProjectSchema 的已创建项目对象

10. update_project

    • 更新现有项目
    • 输入：
      • projectId（字符串）：项目标识符
      • name（可选字符串）：项目名称
      • color（可选字符串）：项目颜色
      • sortOrder（可选数字）：项目排序顺序
      • viewMode（可选字符串）：视图模式（'list'、'kanban'、'timeline'）
      • kind（可选字符串）：项目类型（'TASK'、'NOTE'）
    • 返回：符合 TickTickProjectSchema 的已更新项目对象

11. delete_project

    • 删除项目
    • 输入：
      • projectId（字符串）：项目标识符
    • 返回：无

架构参考

• TickTickTaskSchema：定义任务对象的结构，包括：

  • 基本任务属性（id、title、description）
  • 日期和时间设置
  • 优先级和状态
  • 清单项和子任务

• TickTickProjectSchema：定义项目对象的结构，包括：

  • 项目标识和名称
  • 显示设置（颜色、视图模式）
  • 权限和组织方式

任务属性

创建或更新任务时，可以包含以下属性：

• 优先级别：
  • 0：无
  • 1：低
  • 3：中
  • 5：高
• 状态值：
  • 0：正常（未完成）
  • 2：已完成
• 提醒格式：
  • 示例：["TRIGGER:P0DT9H0M0S", "TRIGGER:PT0S"]
  • 遵循 iCalendar TRIGGER 格式
• 重复规则（repeatFlag）：
  • 示例："RRULE:FREQ=DAILY;INTERVAL=1"
  • 使用 RFC 5545 重复规则
• 日期格式：
  • ISO 8601 格式："yyyy-MM-dd'T'HH:mm:ssZ"
  • 示例："2019-11-13T03:00:00+0000"

项目属性

创建或更新项目时，可以使用以下属性：

• 视图模式：
  • "list"：标准列表视图
  • "kanban"：看板视图
  • "timeline"：时间线视图
• 项目类型：
  • "TASK"：面向任务的项目
  • "NOTE"：面向笔记的项目

设置

OAuth 身份验证

要启用 TickTick 的 OAuth 身份验证，需要注册应用并获取 API 凭据：

• 在 TickTick Developer Portal 创建账户
• 注册新应用
• 将 OAuth 重定向 URL 设置为：http://localhost:8000/callback
• 复制生成的 Client ID（TICKTICK_CLIENT_ID）和 Client Secret（TICKTICK_CLIENT_SECRET）

首次授权流程

首次使用 TickTick MCP 服务时：

1. 系统会提示你授权应用
2. 浏览器窗口将打开 TickTick 登录页面
3. 登录后，系统会要求你授予权限
4. 页面将显示访问令牌
5. 复制此令牌，并将其设置为 TICKTICK_ACCESS_TOKEN 环境变量

生成访问令牌

需要生成新的访问令牌时（首次设置或令牌过期时），请按以下步骤操作：

1. 使用以下任一方法配置凭据：

   选项 1：.env 文件（推荐）

   在项目根目录中创建一个 .env 文件：

   TICKTICK_CLIENT_ID="<YOUR_CLIENT_ID>"
   TICKTICK_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
   

   然后加载该文件：

   source .env
   

   推荐使用此方法，因为：

   • 凭据会在不同终端会话之间保留
   • 更便于管理多个配置
   • 不易因 shell 历史记录而泄露
   • 便于备份（请记得从版本控制中排除）

   选项 2：终端环境变量

   如果凭据中包含特殊字符，请使用单引号。请注意，这些变量只会在当前终端会话中保留：

   export TICKTICK_CLIENT_ID='<YOUR_CLIENT_ID>'
   export TICKTICK_CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
   

2. 运行身份验证命令：

   如果使用已发布的软件包：

   npx @alexarevalo.ai/mcp-server-ticktick ticktick-auth
   

   如果在本地运行 MCP 服务：

   npm run start:auth
   

   此过程将：

   • 启动默认浏览器
   • 将你带到 TickTick 登录页面
   • 请求所需权限
   • 生成并显示访问令牌

3. 保存访问令牌：

   echo "TICKTICK_ACCESS_TOKEN=\"<GENERATED_TOKEN>\"" >> .env
   source .env
   

安全提示：

• 将 .env 添加到 .gitignore 文件中
• 切勿将凭据提交到版本控制中
• 访问令牌会在 180 天后过期，你需要重新生成

与 Claude Desktop 搭配使用

要与 Claude Desktop 搭配使用，请将以下内容添加到 claude_desktop_config.json：

NPX

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@alexarevalo.ai/mcp-server-ticktick"],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "ticktick": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TICKTICK_CLIENT_ID",
        "-e",
        "TICKTICK_CLIENT_SECRET",
        "-e",
        "TICKTICK_ACCESS_TOKEN",
        "mcp/ticktick"
      ],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 ticktick-mcp-server：

npx -y @smithery/cli install @alexarevalo9/ticktick-mcp-server --client claude

构建

Docker 构建：

docker build -t mcp/ticktick -f src/ticktick/Dockerfile .

许可证

此 MCP 服务采用 MIT License 许可。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT License 的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。