TickTick MCP 服务器

⚠️ 注意: 本项目目前正在积极开发中。功能和文档可能不完整或 subject to change。

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

功能

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

工具

1. get_task_by_ids

   • 通过项目 ID 和任务 ID 获取特定任务
   • 输入:
     • projectId (字符串): 项目标识符
     • taskId (字符串): 任务标识符
   • 返回: 完整的任务详细信息，包括子任务

2. create_task

   • 在项目中创建新任务
   • 输入:
     • title (字符串): 任务标题
     • projectId (字符串): 项目标识符
     • content (可选字符串): 任务内容/描述
     • desc (可选字符串): 清单描述
     • isAllDay (可选布尔值): 全天标志
     • startDate (可选字符串): ISO 格式的开始日期和时间
     • dueDate (可选字符串): ISO 格式的截止日期和时间
     • timeZone (可选字符串): 日期时区
     • reminders (可选数组): 提醒触发器列表
     • repeatFlag (可选字符串): 任务的重复规则
     • priority (可选整数): 任务优先级 (0-5)
     • sortOrder (可选整数): 任务排序
     • items (可选数组): 子任务列表
   • 返回: 创建的任务详细信息

3. update_task

   • 更新现有任务
   • 输入:
     • taskId (字符串): 任务标识符
     • id (字符串): 任务 ID
     • projectId (字符串): 项目标识符
     • title (可选字符串): 任务标题
     • content (可选字符串): 任务内容
     • desc (可选字符串): 清单描述
     • isAllDay (可选布尔值): 全天标志
     • startDate (可选字符串): 开始日期和时间
     • dueDate (可选字符串): 截止日期和时间
     • timeZone (可选字符串): 时区
     • reminders (可选数组): 提醒触发器列表
     • repeatFlag (可选字符串): 重复规则
     • priority (可选整数): 任务优先级
     • sortOrder (可选整数): 任务排序
     • items (可选数组): 子任务列表
   • 返回: 更新的任务详细信息

4. complete_task

   • 将任务标记为已完成
   • 输入:
     • projectId (字符串): 项目标识符
     • taskId (字符串): 任务标识符
   • 返回: 成功确认

5. delete_task

   • 从项目中删除任务
   • 输入:
     • projectId (字符串): 项目标识符
     • taskId (字符串): 任务标识符
   • 返回: 成功确认

6. get_user_projects

   • 获取已验证用户的所有项目
   • 输入: 无
   • 返回: 项目详细信息数组

7. get_project_by_id

   • 通过 ID 获取特定项目
   • 输入:
     • projectId (字符串): 项目标识符
   • 返回: 项目详细信息

8. get_project_with_data

   • 获取项目详细信息以及任务和列
   • 输入:
     • projectId (字符串): 项目标识符
   • 返回: 项目数据，包括任务和看板列

9. create_project

   • 创建新项目
   • 输入:
     • name (字符串): 项目名称
     • color (可选字符串): 项目颜色 (例如, "#F18181")
     • sortOrder (可选整数): 排序值
     • viewMode (可选字符串): 视图模式 ("list", "kanban", "timeline")
     • kind (可选字符串): 项目类型 ("TASK", "NOTE")
   • 返回: 创建的项目详细信息

10. update_project

    • 更新现有项目
    • 输入:
      • projectId (字符串): 项目标识符
      • name (可选字符串): 项目名称
      • color (可选字符串): 项目颜色
      • sortOrder (可选整数): 排序值
      • viewMode (可选字符串): 视图模式
      • kind (可选字符串): 项目类型
    • 返回: 更新的项目详细信息

11. delete_project

    • 删除项目
    • 输入:
      • projectId (字符串): 项目标识符
    • 返回: 成功确认

任务属性

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

• 优先级:
  • 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 开发者门户 上创建一个帐户
• 注册一个新应用程序
• 将 OAuth 重定向 URL 设置为：http://localhost:8000/callback
• 复制生成的客户端 ID (TICKTICK_CLIENT_ID) 和客户端密钥 (TICKTICK_CLIENT_SECRET)

首次授权流程

首次使用 TickTick MCP 服务器时：

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

重新身份验证（令牌过期或首次身份验证失败）

如果令牌过期或首次身份验证不起作用，请按照以下步骤使用 npx 重新进行身份验证：

1. 使用您的客户端 ID 和客户端密钥设置环境变量。如果您的凭据包含特殊字符，请使用单引号以防止 zsh 或 bash 解释它们，或者使用 .env 文件。

   选项 1：使用 export 和单引号（对于特殊字符）：

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

   选项 2：使用 .env 文件：

   1. 在您的项目目录中创建一个 .env 文件：

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

   2. 通过运行以下命令加载环境变量：

   source .env
   

2. 设置环境变量后，运行以下 npx 命令以触发身份验证：

   npx @alexarevalo9/mcp-server-ticktick ticktick-auth
   

   这将：

   • 提示您重新授权该应用程序
   • 打开一个浏览器窗口进行登录
   • 允许您再次授予请求的权限
   • 显示新的访问令牌

3. 身份验证后，复制新的访问令牌并将其设置为 TICKTICK_ACCESS_TOKEN 环境变量，以继续使用该应用程序。

与 Claude Desktop 一起使用

要将其与 Claude Desktop 一起使用，请将以下内容添加到您的 claude_desktop_config.json：

NPX

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@alexarevalo9/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>"
      }
    }
  }
}

构建

Docker 构建:

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

许可证

此 MCP 服务器已获得 MIT 许可证的许可。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。有关更多详细信息，请参阅项目存储库中的 LICENSE 文件。