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库与 TickTick API 进行交互。

先决条件

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

设置

**注册 TickTick 应用程序：**在使用服务器之前，您需要向 TickTick 注册一个应用程序以获取 API 凭证。请根据ticktick-py文档执行以下步骤：
- 前往TickTick OpenAPI 文档并使用您的 TickTick 帐户登录。
- 点击右上角的Manage Apps 。
- 点击+App Name按钮注册新应用。请输入您的应用名称（例如，“MCP 服务器”）。
- 创建完成后，编辑应用详情。记下生成的Client ID和Client Secret 。
- 对于OAuth Redirect URL ，请输入授权应用程序后要重定向到的 URL。它不需要是实际的 URL
  - http://localhost:8080/redirect或http://127.0.0.1:8080/是本地开发的常见选择。
  - 确保此精确的 URL 保存在您的环境变量中。
**环境变量：**服务器需要您刚刚获得的 TickTick API 凭据，以及您的 TickTick 登录详细信息。默认情况下，它会查找位于~/.config/ticktick-mcp/.env的.env文件。
- 如果不存在，服务器可能会创建~/.config/ticktick-mcp/目录，但手动创建更安全。
- 您必须在该目录中手动创建.env文件。
- 或者，你可以使用--dotenv-dir命令行参数指定其他目录，但仅限通过 Python 直接运行服务器时（请参阅下文“运行服务器”）。 .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)

**身份验证（首次运行）：**首次运行时（直接或通过 MCP 客户端），底层ticktick-py库将启动 OAuth2 身份验证流程。
- Web 浏览器窗口可能会自动打开，或者在控制台/日志输出中打印 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任务管理服务交互：

任务管理

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 （对象数组，可选）：子任务字典列表。
ticktick_update_task
- 更新现有任务
- 输入：
  - task_object （对象）：要更新的任务属性的字典，包括任务id 。
ticktick_delete_tasks
- 删除一个或多个任务
- 输入：
  - task_ids （字符串或字符串数组）：要删除的单个任务 ID 或任务 ID 列表。
ticktick_complete_task
- 将任务标记为完成
- 输入：
  - task_id （字符串）：要标记为完成的任务的 ID。
ticktick_move_task
- 将任务移至其他项目
- 输入：
  - task_id （字符串）：要移动的任务的 ID。
  - new_project_id （字符串）：目标项目的 ID。
ticktick_make_subtask
- 使一个任务成为另一个任务的子任务
- 输入：
  - parent_task_id （字符串）：将成为父级任务的任务的 ID。
  - child_task_id （字符串）：将成为子任务的任务的 ID。

任务检索

ticktick_get_by_id
- 通过 ID 检索特定对象（任务、项目等）
- 输入：
  - obj_id （字符串）：要检索的对象的唯一 ID。
ticktick_get_all
- 检索指定类型的所有对象
- 输入：
  - search （字符串）：要检索的对象类型（例如“任务”、“项目”、“标签”）。
ticktick_get_tasks_from_project
- 检索特定项目的所有未完成的任务
- 输入：
  - project_id （字符串）：项目的 ID。
ticktick_filter_tasks

根据各种标准过滤任务
输入：
- filter_criteria （对象）：带有过滤参数的字典，例如：
  - status （字符串）：任务状态（“未完成”或“已完成”）。
  - project_id （字符串，可选）：用于过滤任务的项目 ID。
  - tag_label （字符串，可选）：用于过滤任务的标签名称。
  - priority （整数，可选）：优先级。
  - due_start_date （字符串，可选）：到期日过滤器的 ISO 格式的开始日期。
  - due_end_date （字符串，可选）：到期日过滤器的 ISO 格式结束日期。
  - completion_start_date （字符串，可选）：完成日期过滤器的开始日期。
  - completion_end_date （字符串，可选）：完成日期过滤器的结束日期。
  - sort_by_priority （布尔值，可选）：按优先级对结果进行排序。
  - tz （字符串，可选）：用于日期解释的时区。

辅助工具

ticktick_convert_datetime_to_ticktick_format

将 ISO 8601 日期/时间字符串转换为 TickTick API 格式
输入：
- datetime_iso_string （字符串）：ISO 8601 格式的日期/时间字符串。
- tz （字符串）：用于解释日期/时间的 IANA 时区名称。

🤖 代理提示示例

## 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.

🤝 贡献

欢迎贡献代码！欢迎随时创建 issue 或提交 pull request。

📜 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

🔗 另请参阅

模型上下文协议服务器：各种工具和平台的 MCP 服务器参考实现的中央存储库。
modelcontextprotocol.io ：模型上下文协议的官方文档。
pietrozullo/mcp-use ：一个流行的 Python 库，用于构建与 MCP 服务器交互的客户端/代理。
lazeroffmichael/ticktick-py ：该项目用于处理身份验证和 API 交互的非官方 TickTick API 库。

TickTick MCP Server

Integrations