TickTick MCP Server

TickTick MCP 服务

一个提供与 TickTick 任务管理服务集成功能的模型上下文协议（MCP）服务。

功能

• 以增强的显示方式列出任务和项目（优先级易于阅读）
• 创建、更新和删除任务
• 将任务标记为已完成
• 获取特定任务的详细信息
• 处理时区，并手动调整 D+1，以准确计算截止日期
• 获取逾期任务，并可配置时区偏移量
• 获取今日任务，并进行适当的时区补偿
• 支持 OAuth 和用户名/密码身份验证
• 完整支持 TypeScript，并提供完善的错误处理

设置

1. 安装依赖项：

npm install

2. 创建环境配置：

cp .env.example .env

3. 在 .env 中配置身份验证：

选项 A：OAuth（推荐）

TICKTICK_ACCESS_TOKEN=your_oauth_access_token
TICKTICK_REFRESH_TOKEN=your_refresh_token
TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret

选项 B：用户名/密码

TICKTICK_USERNAME=your_ticktick_username
TICKTICK_PASSWORD=your_ticktick_password

OAuth 设置请参阅 OAUTH_SETUP.md，或使用辅助工具：

node oauth-helper.js

4. 构建项目：

npm run build

使用方法

开发

npm run dev

生产

npm start

可用工具

• get_tasks - 获取所有任务或特定项目中的任务（增强显示）
• get_overdue_tasks - 获取逾期任务，并进行时区补偿（可配置偏移量，默认为 UTC+8，请根据你的时区调整）
• get_todays_tasks - 获取今天到期的任务，并进行 D+1 时区调整
• get_projects - 获取 TickTick 中的所有项目
• create_task - 创建包含优先级、标签和截止日期的新任务
• update_task - 更新现有任务
• delete_task - 删除任务
• complete_task - 将任务标记为已完成
• get_task - 根据 ID 获取特定任务

时区处理

此服务包含手动时区变通方案，用于处理 TickTick 的时区不一致问题：

• D+1 调整：自动将截止日期增加 1 天，以补偿时区差异
• 可配置偏移量：get_overdue_tasks 接受 timezoneOffsetHours 参数
  • 默认值：8（UTC+8）——请根据你的时区更改此值！
  • 示例：
    • EST（UTC-5）：timezoneOffsetHours: -5
    • UTC：timezoneOffsetHours: 0
    • JST（UTC+9）：timezoneOffsetHours: 9
    • CET（UTC+1）：timezoneOffsetHours: 1
• 全天任务与定时任务：对全天任务和特定时间的任务采用不同的处理方式
• 增强显示：任务包含易于阅读的优先级文本（None、Low、Medium、High）

重要提示：默认时区偏移量为 UTC+8。调用 get_overdue_tasks 时，请指定正确的时区偏移量，以便获取适用于你所在位置的准确结果。

MCP 集成

Claude Desktop（搭配 Claude Desktop 应用）

将此服务添加到 MCP 客户端配置文件中：

位置： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/path/to/ticktick-mcp-server/dist/index.js"],
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Cursor IDE

将此服务添加到 Cursor MCP 配置中：

位置： 创建或编辑 .cursorrules，或在 Cursor 设置中配置 MCP 服务

{
  "mcp": {
    "servers": {
      "ticktick": {
        "command": "node",
        "args": ["/path/to/ticktick-mcp-server/dist/index.js"],
        "env": {
          "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
          "TICKTICK_REFRESH_TOKEN": "your_refresh_token", 
          "TICKTICK_CLIENT_ID": "your_client_id",
          "TICKTICK_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}

使用用户名/密码的替代方式

{
  "env": {
    "TICKTICK_USERNAME": "your_username",
    "TICKTICK_PASSWORD": "your_password"
  }
}

许可证

MIT