TickTick MCP Server

TickTick MCP 服务

一个适用于 TickTick 的 模型上下文协议（MCP） 服务，可让你通过 Claude 和其他 MCP 客户端直接与 TickTick 任务管理系统交互。

功能

• 📋 查看所有 TickTick 项目和任务
• ✏️ 通过自然语言创建项目和任务
• 🔄 更新现有任务详情（标题、内容、日期、优先级）
• ✅ 将任务标记为已完成
• 🗑️ 删除任务和项目
• 🔄 与 TickTick 开放 API 完全集成
• 🔌 与 Claude 和其他 MCP 客户端无缝集成

前置条件

• Python 3.10 或更高版本
• uv — 快速的 Python 软件包安装程序和解析器
• 拥有 API 访问权限的 TickTick 账户
• TickTick API 凭据（Client ID、Client Secret、Access Token）

安装

1. 克隆此仓库：

   git clone https://github.com/jacepark12/ticktick-mcp.git
   cd ticktick-mcp
   

2. 使用 uv 安装：

   # Install uv if you don't have it already
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Create a virtual environment
   uv venv
   
   # Activate the virtual environment
   # On macOS/Linux:
   source .venv/bin/activate
   # On Windows:
   .venv\Scripts\activate
   
   # Install the package
   uv pip install -e .
   

3. 通过 TickTick 进行身份验证：

   # Run the authentication flow
   uv run -m ticktick_mcp.cli auth
   

   此操作将：

   • 要求你提供 TickTick Client ID 和 Client Secret
   • 打开浏览器窗口，让你登录 TickTick
   • 自动将访问令牌保存到 .env 文件

4. 测试配置：

   uv run test_server.py
   

   此操作将验证你的 TickTick 凭据是否正常工作。

通过 TickTick 进行身份验证

此服务使用 OAuth2 与 TickTick 进行身份验证。设置过程十分简单：

1. 在 TickTick Developer Center 注册应用

   • 将重定向 URI 设置为 http://localhost:8000/callback
   • 记下你的 Client ID 和 Client Secret

2. 运行身份验证命令：

   uv run -m ticktick_mcp.cli auth
   

3. 按照提示输入 Client ID 和 Client Secret

4. 浏览器窗口将打开，你可以使用 TickTick 账户授权此应用

5. 授权后，你将被重定向回应用，访问令牌也会自动保存到 .env 文件

此服务会自动处理令牌刷新，因此除非你撤销访问权限或删除 .env 文件，否则无需重新进行身份验证。

通过 Dida365 进行身份验证

滴答清单 - Dida365 是 TickTick 的中国版本，身份验证过程与 TickTick 类似。请按照以下步骤设置 Dida365 身份验证：

1. 在 Dida365 Developer Center 注册应用

   • 将重定向 URI 设置为 http://localhost:8000/callback
   • 记下你的 Client ID 和 Client Secret

2. 将环境变量添加到 .env 文件：

   TICKTICK_BASE_URL='https://api.dida365.com/open/v1'
   TICKTICK_AUTH_URL='https://dida365.com/oauth/authorize'
   TICKTICK_TOKEN_URL='https://dida365.com/oauth/token'
   

3. 按照与 TickTick 相同的身份验证步骤操作

与 Claude for Desktop 搭配使用

1. 安装 Claude for Desktop

2. 编辑 Claude for Desktop 配置文件：

   macOS：

   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Windows：

   notepad %APPDATA%\Claude\claude_desktop_config.json
   

3. 使用绝对路径添加 TickTick MCP 服务配置：

   {
      "mcpServers": {
         "ticktick": {
            "command": "<absolute path to uv>",
            "args": ["run", "--directory", "<absolute path to ticktick-mcp directory>", "-m", "ticktick_mcp.cli", "run"]
         }
      }
   }
   

4. 重启 Claude for Desktop

连接后，你会在 Claude 中看到可用的 TickTick MCP 服务工具，并通过 🔨（工具）图标识别。

可用的 MCP 工具

工具	描述	参数
get_projects	列出你的所有 TickTick 项目	无
get_project	获取特定项目的详情	project_id
get_project_tasks	列出项目中的所有任务	project_id
get_task	获取特定任务的详情	project_id、task_id
create_task	创建新任务	title、project_id、content（可选）、start_date（可选）、due_date（可选）、priority（可选）
update_task	更新现有任务	task_id、project_id、title（可选）、content（可选）、start_date（可选）、due_date（可选）、priority（可选）
complete_task	将任务标记为已完成	project_id、task_id
delete_task	删除任务	project_id、task_id
create_project	创建新项目	name、color（可选）、view_mode（可选）
delete_project	删除项目	project_id

任务专用 MCP 工具

任务获取与搜索

工具	描述	参数
get_all_tasks	获取所有项目中的全部任务	无
get_tasks_by_priority	按优先级筛选任务	priority_id（0：无、1：低、3：中、5：高）
search_tasks	按标题、内容或子任务搜索任务	search_term

按日期获取任务

工具	描述	参数
get_tasks_due_today	获取今天到期的所有任务	无
get_tasks_due_tomorrow	获取明天到期的所有任务	无
get_tasks_due_in_days	获取恰好在 X 天后到期的任务	days（0 = 今天，1 = 明天，以此类推）
get_tasks_due_this_week	获取未来 7 天内到期的任务	无
get_overdue_tasks	获取所有已逾期任务	无

完成任务（GTD）框架

工具	描述	参数
get_engaged_tasks	获取“正在处理”的任务（高优先级或已逾期）	无
get_next_tasks	获取“下一步”任务（中优先级或明天到期）	无
batch_create_tasks	一次创建多个任务	tasks（任务字典列表）

Claude 提示词示例

连接 TickTick MCP 服务后，可使用以下提示词与 Claude 交互：

常规

• “显示我的所有 TickTick 项目”
• “在我的工作项目中创建一个名为 ‘Finish MCP server documentation’ 的高优先级新任务”
• “列出我的个人项目中的所有任务”
• “将任务 ‘Buy groceries’ 标记为已完成”
• “创建一个名为 ‘Vacation Planning’、颜色为蓝色的新项目”
• “我在 TickTick 中的下一个截止日期是什么时候？”

任务筛选查询

• “我今天有哪些到期任务？”
• “显示所有已逾期的事项”
• “显示本周到期的所有任务”
• “搜索与 ‘project alpha’ 有关的任务”
• “显示标题或描述中包含 ‘client’ 的所有任务”
• “显示我的所有高优先级任务”

GTD 工作流

遵循 David Allen 的“完成任务”（Getting Things Done）框架，管理“正在处理”和“下一步”行动。

• “正在处理”将获取高优先级、今天到期或已逾期的任务。
• “下一步”将获取中优先级或明天到期的任务。
• 使用 batch_creation 将复杂行动拆分为更小的行动

例如：

• “将我今天剩余时间从下午 2 点到晚上 8 点安排为时间块，并填入‘正在处理’列表中的事项”
• “带我过一遍下一步行动，并帮我确定明天应该专注做什么？”
• “将这个项目拆分为 5 个更小、可执行的任务”

开发

项目结构

ticktick-mcp/
├── .env.template          # Template for environment variables
├── README.md              # Project documentation
├── requirements.txt       # Project dependencies
├── setup.py               # Package setup file
├── test_server.py         # Test script for server configuration
└── ticktick_mcp/          # Main package
    ├── __init__.py        # Package initialization
    ├── authenticate.py    # OAuth authentication utility
    ├── cli.py             # Command-line interface
    └── src/               # Source code
        ├── __init__.py    # Module initialization
        ├── auth.py        # OAuth authentication implementation
        ├── server.py      # MCP server implementation
        └── ticktick_client.py  # TickTick API client

身份验证流程

该项目为 TickTick 实现了完整的 OAuth 2.0 流程：

1. 初始设置：用户提供 TickTick API 客户端 ID 和密钥
2. 浏览器授权：用户被重定向到 TickTick 以授予访问权限
3. 接收令牌：本地服务接收包含授权码的 OAuth 回调
4. 交换令牌：将授权码交换为访问令牌和刷新令牌
5. 存储令牌：令牌会安全地存储在本地 .env 文件中
6. 刷新令牌：访问令牌过期时，客户端会自动刷新

通过以编程方式处理整个 OAuth 流程，简化了用户体验。

贡献

欢迎贡献！请随时提交拉取请求。

1. 复刻该仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起拉取请求

许可证

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