Skip to main content
Glama
enesjakozh
jen6

TickTick MCP Server

by jen6
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

TickTick MCP 服务器

许可证：MIT

使用此 MCP 服务器增强您的 TickTick 工作流程。它基于ticktick-py库构建，显著提升了过滤功能，使 AI 助手和兼容 MCP 的应用程序（例如 Claude Desktop、VS Code Agent Mode 或mcp-use ）能够以更高的精度和性能与您的任务进行交互。

✨ 特点

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

  • **任务管理：**创建、更新（包括转换为TickTick的日期格式）、删除、完成和移动任务。

  • **子任务管理：**通过链接现有任务来创建子任务。

  • 任务检索：

    • 获得所有未完成的任务。

    • 通过 ID 或特定字段获取任务。

    • 获取某个日期范围内已完成的任务。

    • 从特定项目中获取任务。

    • 根据各种标准（优先级、项目、标签等）过滤任务。

  • **项目/标签管理：**检索所有项目、标签和项目文件夹。

  • **辅助工具：**将日期时间字符串转换为所需的 TickTick 格式。

有关详细规格，请参阅src/ticktick_mcp/tools/目录中的工具定义。

Related MCP server: Teamwork MCP

🚀 入门

该服务器利用非官方的ticktick-py与 TickTick API 进行交互。

先决条件

  • Python >= 3.10

  • 访问 TickTick 和 API 凭证（见下文）。

设置

  1. **注册 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 保存在您的环境变量中。

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

    • 如果不存在，服务器可能会创建~/.config/ticktick-mcp/目录，但手动创建更安全。

    • 您必须在该目录中手动创建。

    • 或者，你可以使用--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)

  1. **身份验证（首次运行）：**首次运行时（直接或通过 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任务管理服务交互：

任务管理

  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 （字符串）：要检索的对象类型（例如“任务”、“项目”、“标签”）。

  3. ticktick_get_tasks_from_project

    • 检索特定项目的所有未完成的任务

    • 输入：

      • project_id （字符串）：项目的 ID。

  4. 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 （字符串，可选）：用于日期解释的时区。

辅助工具

  1. 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文件。

🔗 另请参阅

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jen6/ticktick-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server