本项目是 TickTick 的 MCP 服务器实现，允许任何兼容 Model Context Protocol (MCP) 的应用（如一些 AI 助手、集成开发环境插件等）通过结构化的 API 与你的 TickTick 账户进行交互，实现任务的创建、管理、查询等功能。

主要功能点:

任务管理: 创建、更新、删除、完成任务，以及移动任务到不同项目。
子任务管理: 将现有任务关联为另一个任务的子任务。
任务检索: 获取所有未完成任务，按 ID、项目、标签、优先级、截止日期或完成日期等多种条件过滤任务。
项目/标签获取: 获取所有项目、标签和项目文件夹列表。
辅助工具: 转换日期时间格式以符合 TickTick API 要求。

安装步骤:

前提条件:
- 安装 Python 3.10 或更高版本。
- 拥有 TickTick 账户。
注册 TickTick 应用:
- 访问 TickTick OpenAPI 文档网站并登录。
- 进入“Manage Apps”（管理应用）。
- 创建一个新应用，记下生成的 'Client ID' 和 'Client Secret'。
- 设置 'OAuth Redirect URL'（例如 'http://localhost:8080/redirect' 或 'http://127.0.0.1:8080/'），请确保记录下您设置的精确 URL。

配置环境变量:

服务器默认在 '~/.config/ticktick-mcp/' 目录下寻找 '.env' 文件。请手动创建此目录（如果不存在）。
在该目录下手动创建 '.env' 文件。

在 '.env' 文件中填入您的 TickTick API 凭据和账户信息：

TICKTICK_CLIENT_ID=您的Client_ID
TICKTICK_CLIENT_SECRET=您的Client_Secret
TICKTICK_REDIRECT_URI=您设置的OAuth_Redirect_URL
TICKTICK_USERNAME=您的TickTick_登录邮箱
TICKTICK_PASSWORD=您的TickTick_登录密码或应用密码

请确保 'TICKTICK_REDIRECT_URI' 与您在 TickTick 网站上设置的完全一致。

初次认证:
- 当 MCP 客户端首次启动此服务器时，可能会触发 OAuth2 认证流程。
- 系统可能会自动打开浏览器窗口，或在日志中打印认证 URL。
- 您需要在浏览器中访问该 URL，登录 TickTick 并授权应用（通常需要读写权限）。
- 授权成功后，浏览器将重定向到您在步骤 2 中设置的 'TICKTICK_REDIRECT_URI'。该 URL 的参数中会包含一个 'code=' 参数。
- 您需要将这个完整的重定向 URL 复制并粘贴回服务器运行的控制台/终端提示符中。
- 认证成功后，将在 '.env' 文件同目录下生成 '.token-oauth' 文件，存储认证令牌。此步骤通常只需执行一次。

服务器配置（用于 MCP 客户端）:

本项目服务器通常由 MCP 客户端（如 Claude Desktop、VS Code Agent Mode、mcp-use 等）启动和管理。您需要在 MCP 客户端的配置中添加以下信息（具体格式取决于您的客户端）：

{
 "mcpServers": {
  "ticktick": { // 服务器名称，客户端会用 mcp.ticktick 来调用其工具
   "command": "uvx", // 启动命令，uvx 会自动从 PyPI 或 Git 安装并运行 Python 包
   "args": [
    "--from", "git+https://github.com/jen6/ticktick-mcp.git", // 指定从哪个 Git 仓库安装
    "ticktick-mcp" // 指定要运行的包的入口点（即 main.py）
    // 可选：如果您将 .env 文件放在 ~/.config/ticktick-mcp/ 以外的其他位置，
    // 可以在这里添加参数指定： "--dotenv-dir", "/path/to/your/config"
    // 请检查您的 MCP 客户端是否支持传递额外参数。
   ]
  }
  // 可以添加其他 MCP 服务器配置...
 }
}

请参考您的 MCP 客户端文档，了解如何添加外部 MCP 服务器配置。

基本使用方法:

配置完成后，启动您的 MCP 客户端（如 AI 助手）。客户端将自动启动 TickTick MCP 服务器。然后，您就可以通过 AI 助手或客户端的界面/命令，使用 TickTick 的各项功能了。

例如，您可以对 AI 助手说：
- “创建一项标题为‘发送季度报告’的任务。” (AI 可能会调用 'ticktick_create_task')
- “列出我今天截止的所有任务。” (AI 可能会调用 'ticktick_filter_tasks')
- “把‘买牛奶’任务标记为已完成。” (AI 可能会调用 'ticktick_complete_task')
- “我的‘项目 A’里有哪些任务？” (AI 可能会调用 'ticktick_get_tasks_from_project' 或 'ticktick_filter_tasks')

AI 助手会根据您的指令，通过 MCP 协议调用 TickTick MCP 服务器提供的工具来执行操作。

关键词

信息