TickTick MCP 服务器

一个用于TickTick的模型上下文协议(MCP)服务器，使您能够通过Claude和其他MCP客户端直接与您的TickTick任务管理系统进行交互。

功能

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

预备条件

• Python 3.10或更高版本
• uv - 快速的Python包安装器和解析器
• 具有API访问权限的TickTick账户
• TickTick API凭证（客户端ID、客户端密钥、访问令牌）

安装

1. 克隆此仓库：

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

2. 使用uv安装：

   # 如果还没有安装uv，请先安装
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # 创建虚拟环境
   uv venv
   
   # 激活虚拟环境
   # 在macOS/Linux上：
   source .venv/bin/activate
   # 在Windows上：
   .venv\Scripts\activate
   
   # 安装包
   uv pip install -e .
   

3. 与TickTick进行身份验证：

   # 运行身份验证流程
   uv run -m ticktick_mcp.cli auth
   

   这将：

   • 请求您的TickTick客户端ID和客户端密钥
   • 打开浏览器窗口以登录TickTick
   • 自动将访问令牌保存到.env文件中

4. 测试您的配置：

   uv run test_server.py
   

   这将验证您的TickTick凭证是否正确工作。

与TickTick的身份验证

该服务器使用OAuth2与TickTick进行身份验证。设置过程非常简单：

1. 在TickTick开发者中心注册您的应用

   • 将重定向URI设置为http://localhost:8000/callback
   • 记下您的客户端ID和客户端密钥

2. 运行身份验证命令：

   uv run -m ticktick_mcp.cli auth
   

3. 按照提示输入您的客户端ID和客户端密钥

4. 浏览器窗口将打开，让您授权应用与您的TickTick账户

5. 授权后，您将被重定向回应用程序，并且您的访问令牌将自动保存到.env文件中

服务器会自动处理令牌刷新，除非您撤销访问或删除.env文件，否则无需重新认证。

与Dida365的身份验证

Dida365是TickTick在中国的版本，其身份验证过程类似于TickTick。按照以下步骤设置Dida365身份验证：

1. 在Dida365开发者中心注册您的应用

   • 将重定向URI设置为http://localhost:8000/callback
   • 记下您的客户端ID和客户端密钥

2. 向您的.env文件添加环境变量：

   TICKTICK_BASE_URL='https://api.dida365.com/open/v1'
   TICKTICK_AUTH_URL='https://dida365.com/oauth/authorize'
   TICKTICK_TOKEN_URL='https://dida3_65.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": "<绝对路径到uv>",
            "args": ["run", "--directory", "<绝对路径到ticktick-mcp目录>", "-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	获取所有逾期任务	无

Getting Things Done (GTD)框架

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

示例提示供Claude使用

这里有一些示例提示，在连接TickTick MCP服务器后可以与Claude一起使用：

通用

• "显示我所有的TickTick项目"
• "在我的工作项目中创建一个名为'完成MCP服务器文档'的新任务，优先级为高"
• "列出我的个人项目中的所有任务"
• "标记任务'购买杂货'为已完成"
• "创建一个名为'度假计划'的新项目，颜色为蓝色"
• "我的下一个截止日期是什么时候？"

任务过滤查询

• "我今天有哪些任务到期？"
• "显示所有逾期的任务"
• "显示本周到期的所有任务"
• "搜索关于'项目阿尔法'的任务"
• "显示标题或描述中含有'客户'的所有任务"
• "显示我所有高优先级的任务"

GTD工作流

遵循David Allen的“Getting Things Done”框架，管理参与和下一步行动。

• 参与将检索高优先级、今天到期或逾期的任务。
• 下一步将检索中优先级或明天到期的任务。
• 将复杂的行动分解成更小的行动，使用批量创建。

例如：

• "从下午2点到8点的时间块，使用我参与列表中的项目"
• "带我浏览我的下一步行动，并帮我确定明天应该关注什么？"
• "将这个项目分解成5个更小的可执行任务"

开发

项目结构

ticktick-mcp/
├── .env.template          # 环境变量模板
├── README.md              # 项目文档
├── requirements.txt       # 项目依赖
├── setup.py               # 包设置文件
├── test_server.py         # 服务器配置测试脚本
└── ticktick_mcp/          # 主要包
    ├── __init__.py        # 包初始化
    ├── authenticate.py    # OAuth身份验证实用程序
    ├── cli.py             # 命令行界面
    └── src/               # 源代码
        ├── __init__.py    # 模块初始化
        ├── auth.py        # OAuth身份验证实现
        ├── server.py      # MCP服务器实现
        └── ticktick_client.py  # TickTick API客户端

身份验证流程

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

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

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

贡献

欢迎贡献！请随时提交Pull Request。

1. 分叉仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加一些惊人的功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开Pull Request

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。