滴答滴-MCP服务器

Name: 滴答滴-MCP服务器
Author: alexarevalo9

作者：alexarevalo943 星标更新：2025-08-29

安装使用来源：spider==github.com

项目介绍

TickTick MCP Server

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

功能

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

工具

get_task_by_ids
- 根据项目ID和任务ID获取特定任务
- 输入参数：
  - projectId (字符串)：项目标识符
  - taskId (字符串)：任务标识符
- 返回值：匹配 TickTickTaskSchema 的任务对象
create_task
- 在项目中创建新任务
- 输入参数：
  - title (字符串)：任务标题
  - projectId (字符串)：项目ID
  - content (可选字符串)：任务内容
  - desc (可选字符串)：任务描述
  - isAllDay (可选布尔值)：是否全天任务
  - startDate (可选字符串)：任务开始日期，格式为 "yyyy-MM-dd'T'HH:mm:ssZ"
  - dueDate (可选字符串)：任务截止日期，格式为 "yyyy-MM-dd'T'HH:mm:ssZ"
  - timeZone (可选字符串)：任务时区（例如："America/Los_Angeles"）
  - reminders (可选字符串数组)：iCalendar 格式的提醒触发器列表
  - repeatFlag (可选字符串)：iCalendar 格式的任务重复标志
  - priority (可选数字)：任务优先级（无：0，低：1，中：3，高：5）
  - sortOrder (可选字符串)：任务排序顺序
  - items (可选数组)：子任务列表，包含：
    - title (字符串)：子任务项标题
    - startDate (可选字符串)：子任务日期，格式为 "yyyy-MM-dd'T'H:mm:ssZ"
    - isAllDay (可选布尔值)：是否全天子任务项
    - sortOrder (可选数字)：子任务项排序顺序
    - timeZone (可选字符串)：子任务时区
    - status (可选数字)：完成状态（正常：0，已完成：1）
    - completedTime (可选字符串)：完成时间，格式为 "yyyy-MM-dd'T'HH:mm:ssZ"
- 返回值：匹配 TickTickTaskSchema 的创建任务对象
update_task
- 更新现有任务
- 输入参数：
  - taskId (字符串)：任务标识符 - 路径
  - id (字符串)：任务标识符 - 主体
  - projectId (字符串)：项目ID
  - 所有来自 create_task 的可选字段
- 返回值：匹配 TickTickTaskSchema 的更新任务对象
complete_task
- 将任务标记为已完成
- 输入参数：
  - taskId (字符串)：任务标识符
  - projectId (字符串)：项目标识符
- 返回值：无
delete_task
- 从项目中删除任务
- 输入参数：
  - taskId (字符串)：任务标识符
  - projectId (字符串)：项目标识符
- 返回值：无
get_user_projects
- 获取已认证用户的所有项目
- 输入参数：无
- 返回值：匹配 TickTickProjectSchema 的项目对象数组
get_project_by_id
- 根据ID获取特定项目
- 输入参数：
  - projectId (字符串)：项目标识符
- 返回值：匹配 TickTickProjectSchema 的项目对象
get_project_with_data
- 获取项目详情，包括任务和列
- 输入参数：
  - projectId (字符串)：项目标识符
- 返回值：包含以下内容的对象：
  - project：匹配 TickTickProjectSchema 的项目对象
  - tasks：匹配 TickTickTaskSchema 的任务对象数组
  - columns：可选列对象数组，包含：
    - id (可选字符串)
    - projectId (可选字符串)
    - name (可选字符串)
    - sortOrder (可选数字)
create_project
- 创建新项目
- 输入参数：
  - name (字符串)：项目名称
  - color (可选字符串)：项目颜色（默认：'#4772FA'）
  - viewMode (可选字符串)：视图模式（'list'，'kanban'，'timeline'）（默认：'list'）
  - kind (可选字符串)：项目类型（'TASK'，'NOTE'）（默认：'TASK'）
- 返回值：匹配 TickTickProjectSchema 的创建项目对象
update_project
- 更新现有项目
- 输入参数：
  - projectId (字符串)：项目标识符
  - name (可选字符串)：项目名称
  - color (可选字符串)：项目颜色
  - sortOrder (可选数字)：项目排序顺序
  - viewMode (可选字符串)：视图模式（'list'，'kanban'，'timeline'）
  - kind (可选字符串)：项目类型（'TASK'，'NOTE'）
- 返回值：匹配 TickTickProjectSchema 的更新项目对象
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 开发者门户上创建一个账户
注册一个新的应用程序
设置 OAuth 重定向 URL 为：http://localhost:8000/callback
复制生成的客户端ID（TICKTICK_CLIENT_ID）和客户端密钥（TICKTICK_CLIENT_SECRET）

第一次授权流程

当首次使用 TickTick MCP 服务器时：

您将被提示授权应用程序
浏览器窗口将打开 TickTick 登录页面
登录后，您将被要求授予权限
访问令牌将在页面上显示
复制此令牌并将其设置为环境变量 TICKTICK_ACCESS_TOKEN

生成访问令牌

当需要生成新的访问令牌（无论是首次设置还是令牌过期时），请遵循以下步骤：

使用以下方法之一配置您的凭证：

选项 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>'
```
运行认证命令：

如果使用发布的包：
```
npx @alexarevalo.ai/mcp-server-ticktick ticktick-auth
```
如果本地运行 MCP 服务器：
```
npm run start:auth
```
此过程将：
- 启动默认浏览器
- 引导您至 TickTick 登录页面
- 请求必要的权限
- 生成并显示您的访问令牌

保存访问令牌：

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 自动安装 ticktick-mcp-server 用于 Claude Desktop：

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

构建

Docker 构建：

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

许可证

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