Ticktick Mcp

TickTick MCP 服务

借助此 MCP 服务，提升您的 TickTick 工作流。该服务基于 ticktick-py 库构建，提供了显著增强的筛选能力，让 AI 助手和兼容 MCP 的应用（例如 Claude Desktop、VS Code Agent Mode 或 mcp-use）能够更精确、更强大地与您的任务交互。

✨ 功能

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

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

详细说明请参阅 src/ticktick_mcp/tools/ 目录中的工具定义。

🚀 开始使用

此服务使用非官方的 ticktick-py library 与 TickTick API 交互。

前提条件

• Python >= 3.10
• 可访问 TickTick 并拥有 API 凭据（见下文）。

设置

1. 注册 TickTick 应用： 使用服务之前，需要先在 TickTick 注册一个应用，以获取 API 凭据。请根据 ticktick-py 文档执行以下步骤：

   • 前往 TickTick OpenAPI 文档，并使用 TickTick 账号登录。
   • 点击右上角的 Manage Apps。
   • 点击 +App Name 按钮，注册一个新应用。为应用填写名称（例如“MCP Server”）。
   • 创建完成后，编辑应用详情。记下生成的 Client ID 和 Client Secret。
   • 在 OAuth Redirect 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   # Obtained in Step 1
TICKTICK_CLIENT_SECRET=your_client_secret # Obtained in Step 1
TICKTICK_REDIRECT_URI=your_redirect_uri # Entered in Step 1 (must match exactly)
TICKTICK_USERNAME=your_ticktick_email # Your TickTick login email
TICKTICK_PASSWORD=your_ticktick_password # Your TickTick login password (or app password if enabled)

3. 身份验证（首次运行）： 首次运行时（无论是直接运行还是通过 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 Mode 等）以使用该服务。配置示例：

{
 "mcpServers": {
 "ticktick": {
  "command": "uvx",
  "args": [
  "--from",
  "git+https://github.com/jen6/ticktick-mcp.git",
  "ticktick-mcp"
  // Optional: Add "--dotenv-dir", "/path/to/your/config" if needed,
  // but standard clients might not support passing extra args easily.
  ]
 }
 }
}

🔧 工具

此服务提供以下工具，用于与 TickTick 任务管理服务交互：

任务管理

1. ticktick_create_task

   • 在 TickTick 中创建新任务
   • 输入：
     • title (string)：任务标题。必填。
     • projectId (string, optional)：要将任务添加到的项目 ID。
     • content (string, optional)：任务的其他详细信息或备注。
     • desc (string, optional)：任务描述。
     • allDay (boolean, optional)：如果任务持续一整天，则设为 True。
     • startDate (string, optional)：ISO 8601 格式的开始日期/时间。
     • dueDate (string, optional)：ISO 8601 格式的截止日期/时间。
     • timeZone (string, optional)：IANA 时区名称（例如，'Asia/Seoul'）。
     • reminders (array of strings, optional)：RFC 5545 格式的提醒触发器列表。
     • repeat (string, optional)：RFC 5545 格式的重复规则。
     • priority (integer, optional)：任务优先级（0=None，1=Low，3=Medium，5=High）。
     • sortOrder (integer, optional)：自定义排序值。
     • items (array of objects, optional)：子任务字典列表。

2. ticktick_update_task

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

3. ticktick_delete_tasks

   • 删除一个或多个任务
   • 输入：
     • task_ids (string or array of strings)：要删除的单个任务 ID 或任务 ID 列表。

4. ticktick_complete_task

   • 将任务标记为已完成
   • 输入：
     • task_id (string)：要标记为已完成的任务 ID。

5. ticktick_move_task

   • 将任务移至其他项目
   • 输入：
     • task_id (string)：要移动的任务 ID。
     • new_project_id (string)：目标项目的 ID。

6. ticktick_make_subtask

   • 将一个任务设为另一个任务的子任务
   • 输入：
     • parent_task_id (string)：将作为父任务的任务 ID。
     • child_task_id (string)：将作为子任务的任务 ID。

任务检索

7. ticktick_get_by_id

   • 按 ID 获取特定对象（任务、项目等）
   • 输入：
     • obj_id (string)：要获取的对象的唯一 ID。

8. ticktick_get_all

   • 获取指定类型的所有对象
   • 输入：
     • search (string)：要获取的对象类型（例如，'tasks'、'projects'、'tags'）。

9. ticktick_get_tasks_from_project

   • 获取特定项目中的所有未完成任务
   • 输入：
     • project_id (string)：项目 ID。

10. ticktick_filter_tasks

    • 根据各种条件筛选任务
    • 输入：
      • filter_criteria (object)：包含筛选参数的字典，例如：
        • status (string)：任务状态（'uncompleted' 或 'completed'）。
        • project_id (string, optional)：用于筛选任务的项目 ID。
        • tag_label (string, optional)：用于筛选任务的标签名称。
        • priority (integer, optional)：优先级。
        • due_start_date (string, optional)：截止日期筛选的 ISO 格式开始日期。
        • due_end_date (string, optional)：截止日期筛选的 ISO 格式结束日期。
        • completion_start_date (string, optional)：完成日期筛选的开始日期。
        • completion_end_date (string, optional)：完成日期筛选的结束日期。
        • sort_by_priority (boolean, optional)：按优先级对结果排序。
        • tz (string, optional)：用于日期解析的时区。

辅助工具

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

🤖 示例 Agent 提示词

## Persona: Daily Stand-up Agent

- **Role**: AI agent integrated with the user's TickTick account to assist in daily work planning
- **Goal**: Help the user start their day efficiently, focus on key tasks, and break large tasks into manageable subtasks

---

## Core Features & Workflow

1. **Fetch Current Time** 
 - Retrieve current time using `time mcp`.

2. **Session Start & Data Loading** 
 - The user initiates the session with a command like "Start daily stand-up" or "Hello." 
 - Call TickTick MCP API to fetch all tasks due **today**. 
 - Optionally notify the user that data is loading (e.g., "Fetching today's and overdue tasks from TickTick…").

3. **Daily Briefing**
 Good morning! Today's date is {YYYY-MM-DD}. Here's your daily stand-up from TickTick:

 **Tasks Due Today:**
 - Task Name 1
 - Task Name 2
 …

 **Overdue Tasks:**
 - Task Name 3
 - Task Name 4
 …

4. **Select Key Task** 
 > "Which of these tasks would you like to focus on first or must complete today? 
 > Or is there another important task you'd like to add?"

5. **Task Breakdown (Subtask Creation)** 
 - After the user selects a main task, suggest 2–5 specific subtasks needed to complete it. 
 - Example (if "Write project report" is selected):
  1. Draft outline & table of contents (10 min) 
  2. Gather & analyze data (30 min) 
  3. Write section drafts (1 h) 
  4. Review & revise draft (30 min) 
  5. Final submission (10 min)

6. **Confirm & Add Subtasks** 
 - Ask the user to confirm or adjust the suggested subtasks: 
  > "Does this breakdown look good? Any changes?" 
 - Once approved, call MCP to add each subtask to TickTick, setting them as children of the main task if supported, naming them "[Main Task] – [Subtask]". 
 mcp.ticktick.addTask({
  name: "[Main Task] – [Subtask]",
  parentId: "..."
 });

7. **Session Close** 
 > "All subtasks have been added to TickTick. Have a productive day! Anything else I can help with?"

---

## Additional Guidelines

- **Tone & Manner**: Friendly, proactive, and organized. 
- **MCP Interface Examples**: 
 // Fetch today's due tasks
 mcp.ticktick.getTasks({
 filter_criteria: {
  status: "uncompleted",
  tz: "Asia/Seoul",
  due_end_date: "2025-04-29"
 }
 });

 // Add a subtask
 mcp.ticktick.addTask({
 name: "Project Report – Write Draft",
 parentId: "task123"
 });
- **Error Handling**: Inform the user and suggest retrying on MCP call failures. 
- **Clarity**: Present task lists and subtask suggestions clearly. 
- **Plan First**: Use `sequential thinking mcp` to plan steps before adding or modifying tasks.

🤝 参与贡献

欢迎贡献！欢迎提出问题或提交拉取请求。

📜 许可证

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

🔗 另请参阅

• Model Context Protocol Servers：各种工具和平台的 MCP 服务参考实现的中央代码库。
• modelcontextprotocol.io：Model Context Protocol 官方文档。
• pietrozullo/mcp-use：用于构建与 MCP 服务交互的客户端/Agent 的热门 Python 库。
• lazeroffmichael/ticktick-py：本项目使用的非官方 TickTick API 库，用于处理身份验证和 API 交互。