使用说明

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登录详细信息。默认情况下，它会查找 .env 文件位于 ~/.config/ticktick-mcp/.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 （其中包括a code= 参数）返回到终端。
- 验证成功后，a .token-oauth 文件将在与您的文件相同的目录中创建 .env 文件。
- 此文件缓存授权令牌，因此您通常只需要每6个月或令牌无效时执行一次此手动授权步骤。

运行服务器

您可以通过两种主要方式运行服务器：

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

配置您的MCP客户端（如克劳德桌面、VS代码代理模式等）以使用服务器。配置示例：

{
 "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 （string）：任务的标题。必修的。
  - projectId （字符串，可选）：要添加任务的项目的ID。
  - content （字符串，可选）：任务的其他详细信息或注释。
  - desc （字符串，可选）：任务的描述。
  - allDay （布尔值，可选）：如果任务跨越一整天，则设置为True。
  - startDate （字符串，可选）：ISO 8601格式的开始日期/时间。
  - dueDate （字符串，可选）：ISO 8601格式的到期日期/时间。
  - timeZone （字符串，可选）：IANA时区名称（例如，“亚洲/首尔”）。
  - reminders （字符串数组，可选）：RFC 5545格式的提醒触发器列表。
  - repeat （字符串，可选）：RFC 5545格式的重复规则。
  - priority （整数，可选）：任务优先级（0=无，1=低，3=中，5=高）。
  - sortOrder （整数，可选）：自定义排序顺序值。
  - items （对象数组，可选）：子任务字典列表。
ticktick_update_task
- 更新现有任务
- 输入：
  - task_object （object）：一个包含要更新的任务属性（包括任务）的字典 id.
ticktick_delete_tasks
- 删除一个或多个任务
- 输入：
  - task_ids （字符串或字符串数组）：要删除的单个任务ID或任务ID列表。
ticktick_complete_task
- 将任务标记为已完成
- 输入：
  - task_id （string）：要标记为完成的任务的ID。
ticktick_move_task
- 将任务移动到其他项目
- 输入：
  - task_id （string）：要移动的任务的ID。
  - new_project_id （string）：目标项目的ID。
ticktick_make_subtask
- 使一个任务成为另一个任务的子任务
- 输入：
  - parent_task_id （string）：将成为父级的任务的ID。
  - child_task_id （string）：将成为子任务的任务的ID。

任务检索

ticktick_get_by_id
- 按ID检索特定对象（任务、项目等）
- 输入：
  - obj_id （string）：要检索的对象的唯一ID。
ticktick_get_all
- 检索指定类型的所有对象
- 输入：
  - search （string）：要检索的对象类型（例如，“任务”、“项目”、“标签”）。
ticktick_get_tasks_from_project
- 从特定项目中检索所有未完成的任务
- 输入：
  - project_id （string）：项目的ID。
ticktick_filter_tasks
- 根据各种标准筛选任务
- 输入：
  - filter_criteria （object）：具有过滤参数的字典，例如：
    - status （string）：任务状态（“未完成”或“已完成”）。
    - project_id （字符串，可选）：用于筛选任务的项目ID。
    - tag_label （字符串，可选）：用于筛选任务的标记名称。
    - priority （整数，可选）：优先级。
    - due_start_date （字符串，可选）：到期日过滤器的ISO格式开始日期。
    - due_end_date （字符串，可选）：ISO格式的截止日期过滤器。
    - completion_start_date （字符串，可选）：完成日期过滤器的开始日期。
    - completion_end_date （字符串，可选）：完成日期过滤器的结束日期。
    - sort_by_priority （boolean，可选）：按优先级对结果进行排序。
    - tz （字符串，可选）：用于日期解释的时区。

辅助工具

ticktick_convert_datetime_to_ticktick_format
- 将ISO 8601日期/时间字符串转换为TickTick API格式
- 输入：
  - datetime_iso_string （string）：ISO 8601格式的日期/时间字符串。
  - tz （string）：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.

🤝 贡献

欢迎投稿！请随时打开问题或提交拉取请求。

📜 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🔗 另见

模型上下文协议服务器：用于各种工具和平台的MCP服务器参考实现的中央存储库。
模型上下文协议.io：模型上下文协议的官方文件。
pietrozullo/mcp使用：一个流行的Python库，用于构建与MCP服务器交互的客户端/代理。
拉泽罗夫迈克尔/蒂克蒂克：此项目用于处理身份验证和API交互的非官方TickTick API库。

使用说明

TickTick MCP服务器

✨ 特性

🚀 入门指南

先决条件

设置

运行服务器

🔧 工具

任务管理

任务检索

辅助工具

🤖 样品试剂提示

🤝 贡献

📜 许可证

🔗 另见

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

规范工作流管理工具

PostgreSQL管理服务器