TickTick MCP 服务器

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

功能特点

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

前提条件

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

安装步骤

克隆此仓库：

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

使用 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 .

与 TickTick 进行身份验证：
```
# 运行身份验证流程
uv run -m ticktick_mcp.cli auth
```
此过程将：
- 请求你的 TickTick 客户端 ID 和客户端密钥
- 打开浏览器窗口让你登录 TickTick
- 自动将访问令牌保存到 .env 文件中
测试配置：
```
uv run test_server.py
```
这将验证你的 TickTick 凭证是否正常工作。

与 TickTick 的身份验证

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

在 TickTick 开发者中心注册你的应用
- 将重定向 URI 设置为 http://localhost:8000/callback
- 记下你的客户端 ID 和客户端密钥
运行身份验证命令：
```
uv run -m ticktick_mcp.cli auth
```
按照提示输入你的客户端 ID 和客户端密钥
浏览器窗口将打开，让你授权应用访问你的 TickTick 账户
授权后，你将被重定向回应用，访问令牌将自动保存到 .env 文件中

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

与 Dida365 的身份验证

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

在 Dida365 开发者中心注册你的应用
- 将重定向 URI 设置为 http://localhost:8000/callback
- 记下你的客户端 ID 和客户端密钥

在 .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'

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

与桌面版 Claude 配合使用

安装桌面版 Claude

编辑桌面版 Claude 的配置文件：

macOS：

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

Windows：

notepad %APPDATA%\Claude\claude_desktop_config.json

添加 TickTick MCP 服务器配置，使用绝对路径：

{
   "mcpServers": {
      "ticktick": {
         "command": "<uv 的绝对路径>",
         "args": ["run", "--directory", "<ticktick-mcp 目录的绝对路径>", "-m", "ticktick_mcp.cli", "run"]
      }
   }
}

重启桌面版 Claude

连接后，你将在 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`

Claude 的使用示例

以下是连接 TickTick MCP 服务器后可以与 Claude 一起使用的一些示例提示：

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

开发

项目结构

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 流程：

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

这通过程序化处理整个 OAuth 流程简化了用户体验。

贡献

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

分叉仓库
创建你的功能分支（git checkout -b feature/amazing-feature）
提交你的更改（git commit -m 'Add some amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开 Pull Request

许可证

此项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。