星战科技xingzhan.cloud
返回市场
ticktick-mcp

ticktick-mcp

作者：jen636 星标更新：2025-07-23
安装使用来源：spider==github.com

项目介绍

TickTick MCP Server

<!-- 添加相关徽章 -->

License: MIT

<!-- [![PyPI 版本](https://badge.fury.io/py/your-package-name.svg)](https://badge.fury.io/py/your-package-name) -->

通过这个MCP服务器增强您的TickTick工作流程。基于ticktick-py库构建，它提供了显著改进的过滤能力，使AI助手和兼容MCP的应用程序（如Claude Desktop、VS Code Agent模式或mcp-use）能够更精确和强大地与您的任务进行交互。

✨ 功能

此服务器通过MCP工具提供对TickTick功能的全面访问，分类如下：

  • 任务管理： 创建、更新（包括转换为TickTick日期格式）、删除、完成和移动任务。
  • 子任务管理： 通过链接现有任务创建子任务。
  • 任务检索：
    • 获取所有未完成的任务。
    • 根据ID或特定字段获取任务。
    • 获取指定日期范围内的已完成任务。
    • 获取来自特定项目的任务。
    • 根据各种条件（优先级、项目、标签等）筛选任务。
  • 项目/标签管理： 检索所有项目、标签和项目文件夹。
  • 辅助工具： 将日期时间字符串转换为所需的TickTick格式。

请参阅src/ticktick_mcp/tools/目录中的工具定义以获取详细规范。

🚀 快速开始

此服务器使用非官方的ticktick-py库与TickTick API进行交互。

先决条件

  • Python >= 3.10
  • 访问TickTick和API凭证（见下文）。

设置

  1. 注册TickTick应用程序： 在使用服务器之前，您需要在TickTick上注册一个应用程序以获得API凭证。根据ticktick-py文档中的步骤操作：

    • 转到TickTick OpenAPI 文档，并使用您的TickTick帐户登录。
    • 在右上角点击管理应用。
    • 通过点击+App 名称按钮注册新应用。为您的应用提供一个名称（例如，“MCP Server”）。
    • 创建后，编辑应用详情。记下生成的客户端ID和客户端密钥。
    • 对于OAuth重定向URL，输入授权应用后要跳转到的URL。该URL不需要是实时的。
      • 常见的选择有http://localhost:8080/redirect或http://127.0.0.1:8080/，适用于本地开发。
      • 确保准确保存此URL到环境变量中。

  2. 环境变量： 服务器需要您刚刚获得的TickTick API凭证以及您的TickTick登录详情。默认情况下，它会查找位于~/.config/ticktick-mcp/.env的.env文件。

    • 服务器可能会创建~/.config/ticktick-mcp/目录（如果不存在），但手动创建更安全。
    • 您必须在该目录内手动创建.env文件。
    • 或者，您可以在直接通过Python运行服务器时使用--dotenv-dir命令行参数指定不同的目录（见“运行服务器”部分）。

    .env文件应包含以下内容：

TICKTICK_CLIENT_ID=your_client_id   # 在步骤1中获得
TICKTICK_CLIENT_SECRET=your_client_secret # 在步骤1中获得
TICKTICK_REDIRECT_URI=your_redirect_uri # 在步骤1中输入（必须完全匹配）
TICKTICK_USERNAME=your_ticktick_email # 您的TickTick登录邮箱
TICKTICK_PASSWORD=your_ticktick_password # 您的TickTick登录密码（如果启用了应用密码，则为应用密码）
  1. 认证（首次运行）： 首次运行（无论是直接运行还是通过MCP客户端运行），底层的ticktick-py库将启动OAuth2认证流程。
    • 浏览器窗口可能会自动打开，或者控制台/日志输出中会打印一个URL。
    • 您需要访问该URL，如有必要，请登录TickTick，并授权应用（授予读写权限）。
    • 授权后，您将被重定向到您指定的TICKTICK_REDIRECT_URI。
      • 控制台将提示您将完整的重定向URL（包含code=参数）粘贴回终端。
    • 成功验证后，将在.env文件所在目录创建一个.token-oauth文件。
    • 该文件缓存了授权令牌，因此通常每6个月或当令牌失效时只需执行一次手动授权步骤。

运行服务器

您可以采用两种主要方式运行服务器：

1. 通过MCP客户端（推荐用于AI助手集成）：

配置您的MCP客户端（如Claude Desktop、VS Code Agent模式等）以使用该服务器。示例配置：

{
 "mcpServers": {
 "ticktick": {
  "command": "uvx",
  "args": [
  "--from",
  "git+https://github.com/jen6/ticktick-mcp.git",
  "ticktick-mcp"
  // 可选：如果需要，添加"--dotenv-dir", "/path/to/your/config"，
  // 但标准客户端可能不支持轻松传递额外参数。
  ]
 }
 }
}

🔧 工具

此服务器提供了以下工具，用于与TickTick任务管理系统进行交互：

任务管理

  1. ticktick_create_task

    • 在TickTick中创建一个新的任务
    • 输入：
      • title (字符串)：任务的标题。必需。
      • projectId (字符串，可选)：要添加任务的项目的ID。
      • content (字符串，可选)：任务的附加细节或笔记。
      • desc (字符串，可选)：任务的描述。
      • allDay (布尔值，可选)：设置为True表示任务持续一整天。
      • startDate (字符串，可选)：开始日期/时间，ISO 8601格式。
      • dueDate (字符串，可选) ：到期日期/时间，ISO 8601格式。
      • timeZone (字符串，可选)：IANA时区名称（例如，'Asia/Seoul'）。
      • reminders (字符串数组，可选)：提醒触发器列表，RFC 5545格式。
      • repeat (字符串，可选)：重复规则，RFC 5545格式。
      • priority (整数，可选)：任务优先级（0=无，1=低，3=中，5=高）。
      • sortOrder (整数，可选)：自定义排序顺序值。
      • items (对象数组，可选)：子任务字典列表。

  2. ticktick_update_task

    • 更新现有任务
    • 输入：
      • task_object (对象)：包含要更新的任务属性的字典，包括任务id。

  3. ticktick_delete_tasks

    • 删除一个或多个任务
    • 输入：
      • task_ids (字符串或字符串数组)：要删除的单个任务ID或任务ID列表。

  4. ticktick_complete_task

    • 标记任务为已完成
    • 输入：
      • task_id (字符串)：要标记为已完成的任务ID。

  5. ticktick_move_task

    • 将任务移动到另一个项目
    • 输入：
      • task_id (字符串)：要移动的任务ID。
      • new_project_id (字符串)：目标项目的ID。

  6. ticktick_make_subtask

    • 将一个任务设为另一个任务的子任务
    • 输入：
      • parent_task_id (字符串)：将成为父任务的任务ID。
      • child_task_id (字符串)：将成为子任务的任务ID。

任务检索

  1. ticktick_get_by_id

    • 根据ID检索特定对象（任务、项目等）
    • 输入：
      • obj_id (字符串)：要检索的对象的唯一ID。

  2. ticktick_get_all

    • 检索指定类型的所有对象
    • 输入：
      • search (字符串)：要检索的对象类型（例如，'tasks'，'projects'，'tags'）。

  3. ticktick_get_tasks_from_project

    • 检索特定项目中的所有未完成任务
    • 输入：
      • project_id (字符串)：项目的ID。

  4. ticktick_filter_tasks

    • 根据各种条件筛选任务
    • 输入：
      • filter_criteria (对象)：包含筛选参数的字典，例如：
        • status (字符串)：任务状态（'uncompleted'或'completed'）。
        • project_id (字符串，可选)：按项目ID筛选任务。
        • tag_label (字符串，可选)：按标签名称筛选任务。
        • priority (整数，可选)：优先级级别。
        • due_start_date (字符串，可选)：到期日期筛选的ISO格式起始日期。
        • due_end_date (字符串，可选)：到期日期筛选的ISO格式结束日期。
        • completion_start_date (字符串，可选)：完成日期筛选的起始日期。
        • completion_end_date (字符串，可选)：完成日期筛选的结束日期。
        • sort_by_priority (布尔值，可选)：按优先级排序结果。
        • tz (字符串，可选)：用于日期解释的时区。

辅助工具

  1. ticktick_convert_datetime_to_ticktick_format
    • 将ISO 8601日期/时间字符串转换为TickTick API格式
    • 输入：
      • datetime_iso_string (字符串)：ISO 8601格式的日期/时间字符串。
      • tz (字符串)：用于解释日期/时间的IANA时区名称。

🤖 示例代理提示

## 角色：每日站会代理

- **角色**：集成到用户TickTick账户的AI代理，协助日常工作任务规划
- **目标**：帮助用户高效地开始一天的工作，专注于关键任务，并将大型任务分解成可管理的子任务

---

## 核心功能及工作流程

1. **获取当前时间**
 - 使用`time mcp`检索当前时间。

2. **会话启动及数据加载**
 - 用户通过命令如“开始每日站会”或“你好”启动会话。
 - 调用TickTick MCP API获取今天到期的所有任务。
 - 可选通知用户正在加载数据（例如，“从TickTick获取今天的和逾期的任务…”）。

3. **每日简报**
 早上好！今天的日期是{YYYY-MM-DD}。这是您来自TickTick的每日站会：

 **今天到期的任务：**
 - 任务名称1
 - 任务名称2
 …

 **逾期任务：**
 - 任务名称3
 - 任务名称4
 …

4. **选择关键任务**
 > “您想首先关注这些任务中的哪一个，或者今天必须完成的任务是什么？
 > 或者还有其他重要的任务需要添加？”

5. **任务分解（子任务创建）**
 - 用户选择一个主任务后，建议需要完成它的2-5个具体子任务。
 - 示例（如果选择了“撰写项目报告”）：
  1. 草拟大纲及目录（10分钟）
  2. 收集并分析数据（30分钟）
  3. 撰写章节草稿（1小时）
  4. 审查并修订草稿（30分钟）
  5. 最终提交（10分钟）

6. **确认并添加子任务**
 - 询问用户是否确认或调整建议的子任务：
  > “这个分解看起来合适吗？有任何更改？”
 - 批准后，调用MCP添加每个子任务到TickTick，如果支持的话，将其设置为主任务的子任务，命名格式为“[主任务] – [子任务]”。
 mcp.ticktick.addTask({
  name: "[主任务] – [子任务]",
  parentId: "..."
 });

7. **会话结束**
 > “所有子任务已添加到TickTick。祝您高效的一天！还有其他我能帮忙的吗？”

---

## 额外指南

- **语气与态度**：友好、主动且有条理。
- **MCP接口示例**：
 // 获取今天到期的任务
 mcp.ticktick.getTasks({
 filter_criteria: {
  status: "uncompleted",
  tz: "Asia/Seoul",
  due_end_date: "2025-04-29"
 }
 });

 // 添加一个子任务
 mcp.ticktick.addTask({
 name: "项目报告 – 撰写草稿",
 parentId: "task123"
 });
- **错误处理**：告知用户并在MCP调用失败时建议重试。
- **清晰度**：清晰呈现任务列表和子任务建议。
- **先计划**：使用`sequential thinking mcp`来规划步骤，然后再添加或修改任务。

🤝 贡献

欢迎贡献！请随意打开问题或提交拉取请求。

📜 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

🔗 相关链接