TickTick MCP 服务器

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

功能

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

先决条件

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

安装

1. 克隆此存储库：

   bash 复制代码

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

2. 使用uv安装：

   bash 复制代码

   # 如果尚未安装，先安装 uv
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # 创建虚拟环境
   uv venv
   
   # 激活虚拟环境
   # macOS/Linux:
   source .venv/bin/activation
   # Windows:
   .venv\Scripts\activate
   
   # 安装包
   uv pip install -e 。

3. 与 TickTick 身份验证:

   bash 复制代码

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

   这将：

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

4. 测试您的配置:

   bash 复制代码

   uv run test_server.py

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

使用 TickTick 身份验证

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

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

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

2. 运行身份认证命令:

   bash 复制代码

   uv run -m ticktick_mcp.cli auth

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

4. 一个浏览器窗口将会打开以授权应用访问您的 TickTick 帐号

5. 授权后，您会被重定向回应用，默认位置的访问令牌就会自动保存在.env文件中

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

与 Clauded 桌面配合使用

1. 安装 Claude 桌面版

2. 编辑您的 Clauded 桌面版配置文件:

   macOS:

   bash 复制代码

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

   Windows:

   bash 复制代码

   notepad %APPDATA%\Claude\claude_desktop_config.json

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

   json 复制代码

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

4. 重启 Clauded 桌面版

连接后，您将在 Clauded 中看到 TickTick MCP 服务器工具可用，标志是 🔨（工具）图标。

可用的 MCP 工具

针对 Clauded 输入的示例

以下是一些输入示例，可在连接TickTick MCP服务器后与Clauded一起使用：

• "显示我的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 流程：

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

这样做简化用户体验，通过自动化整个OAuth流程降低了用户的复杂性。

贡献

欢迎贡献！请随意提交 pull 请求。

1. 克隆存储库。
2. 切换到特征分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m '增加一些惊人功能')。
4. 向该分支机构推送 (git push origin feature/amazing-feature)。
5. 张贴一个请求拉动。

许可证

本项目由MIT许可证授予 - 请查看 LICENSE 文件了解详细信息。