使用说明

TickTick MCP服务器

A. 模型上下文协议（MCP） TickTick服务器，允许直接通过Claude和其他MCP客户端与您的TickTick任务管理系统进行交互。

特性

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

先决条件

Python 3.10或更高版本
具有API访问权限的TickTick帐户
TickTick API凭据（客户端ID、客户端机密、访问令牌）

安装

克隆此存储库:

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

用管道安装3:

# Create a virtual environment
python3 -m venv .venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install the package
pip3 install -e .

使用TickTick进行身份验证:
```
# Run the authentication flow
python3 -m ticktick_mcp.cli auth
```
这将：
- 询问您的TickTick客户端ID和客户端密码
- 打开浏览器窗口，让您登录TickTick
- 自动将您的访问令牌保存到 .env 文件
测试您的配置:
```
python3 test_server.py
```
这将验证您的TickTick凭据是否正常工作。

使用Google日历进行身份验证（可选）

这 get_tasks_and_events_for_date 该工具与谷歌日历集成，在TickTick任务旁边显示您的日历事件。要启用此功能，请执行以下操作：

1.创建Google云项目并启用日历API

首选谷歌云控制台
创建新项目或选择现有项目
启用Google日历API：
- 首选 API和服务 > 图书馆
- 搜索“Google日历API”
- 点击启用

2.创建OAuth 2.0凭据

首选 API和服务 > 凭证
点击 创建凭据 > OAuth客户端ID
如果出现提示，请配置OAuth同意屏幕：
- 用户类型：外部（或内部如果使用谷歌工作区）
- 将您的电子邮件添加为测试用户
- 范围：添加 ../auth/calendar.readonly
应用程序类型： 桌面应用
下载凭据JSON文件
将其重命名为 credentials.json 并将其放置在项目根目录中

3.首次身份验证

当你第一次使用 get_tasks_and_events_for_date 工具：

浏览器窗口将自动打开
使用您的Google帐户登录(ashish.dev@salesforce.com)
授予访问日历的权限
该工具将保存 token.json 文件以备将来使用

4.环境变量（可选）

您可以在您的 .env 文件：

GOOGLE_CALENDAR_CREDENTIALS_PATH=/path/to/credentials.json
GOOGLE_CALENDAR_TOKEN_PATH=/path/to/token.json

注：需要进行Google日历身份验证 get_tasks_and_events_for_date 工具。如果未设置，该工具将返回错误。

Google日历身份验证故障排除

如果您在Google日历集成中遇到错误：

“初始化Google日历客户端失败”

核实一下 credentials.json 存在于您的项目根目录中
检查MCP服务器日志以了解详细的错误消息
确保您已完成上述OAuth设置中的所有步骤

“令牌已过期或吊销”或“invalid_grant”错误

删除 token.json 从项目根目录创建文件
重新启动MCP服务器
打电话给 get_tasks_and_events_for_date 再次使用工具触发重新身份验证
浏览器窗口将打开，供您重新授权

日历事件未显示

检查工具是否返回“未找到日历事件”-如果您当天没有事件，这可能是准确的
确保您使用的日历ID正确（默认为“主”）
验证您在OAuth同意期间授予了日历读取权限

修改代码以修复错误后

始终重新启动MCP服务器以使更改生效
Python代码在启动时加载到内存中

使用TickTick进行身份验证

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

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

服务器会自动处理令牌刷新，因此除非您撤销访问权限或删除您的 .env 文件。

时区配置

默认情况下，服务器使用系统的本地时区进行日期比较（例如，确定哪些任务今天到期、逾期等）。如果你想指定一个不同的时区，你可以添加 TICKTICK_TIMEZONE 环境变量到您的 .env 文件：

TICKTICK_TIMEZONE=America/New_York  # For EST/EDT

有效的时区值遵循 IANA时区数据库格式。示例：

America/New_York -东部时间（美国东部时间/美国东部时间）
America/Chicago -中部时间（CST/CDT）
America/Los_Angeles -太平洋时间（PST/PDT）
Europe/London -英国时间（GMT+BST）
Asia/Tokyo -日本标准时间（JST）

如果 TICKTICK_TIMEZONE 变量未设置或无效，服务器将使用您系统的本地时区。

使用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 for Desktop

安装桌面版Claude

编辑您的Claude for Desktop配置文件：

macOS:

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

视窗:

notepad %APPDATA%\Claude\claude_desktop_config.json

使用绝对路径添加TickTick MCP服务器配置：
```
{
   "mcpServers": {
      "ticktick": {
         "command": "<absolute path to python from your virtual environment>",
         "args": ["-m", "ticktick_mcp.cli", "run"]
      }
   }
}
```
备注：对于 command，您需要提供Python解释器的完整、绝对路径 .venv 目录（例如。， /path/to/ticktick-mcp/.venv/bin/python).为了使其正常工作，您可能需要从您的 ticktick-mcp 项目目录。
重新启动桌面版的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`, `description` （可选）， `kind` （可选）， `checklist_items` （可选）， `start_date` （可选）， `due_date` （可选）， `priority_x` （可选）
`update_task`	更新现有任务	`task_id`, `project_id`, `title` （可选）， `checklist_items` （可选）， `start_date` （可选）， `due_date` （可选）， `priority_x` （可选）， `time_zone` （可选）， `is_all_day` （可选）， `reminders` （可选）， `repeat_flag` （可选）
`complete_task`	将任务标记为已完成	`project_id`, `task_id`
`delete_task`	删除任务	`project_id`, `task_id`
`create_project`	创建新项目	`name`, `color` （可选）， `view_mode` （可选）
`delete_project`	删除项目	`project_id`
`create_subtask`	为父任务创建子任务	`subtask_title`, `parent_task_id`, `project_id`, `content` （可选）， `priority_x` （可选）
`update_description`	仅更新任务的描述	`task_id`, `project_id`, `description`, `kind`
`change_to_checklist`	将TEXT任务更改为CHECKLIST任务	`task_id`, `project_id`
`add_checklist_item`	将检查表项添加到checklist任务中	`task_id`, `project_id`, `checklist_item`, `start_date` （可选）

特定任务的MCP工具

任务检索和搜索

工具	说明	参数
`get_all_tasks`	从所有项目中获取所有任务	无
`get_tasks_by_priority`	按优先级筛选任务	`priority_id` （0：无，1：低，3：中，5：高）
`search_tasks`	按标题、内容或子任务搜索任务	`search_term`, `include_completed` （可选）

基于日期的任务检索

工具	说明	参数
`get_tasks_due_in_days`	在X天内完成任务	`days` （0=今天，1=明天，以此类推）
`get_tasks_due_this_week`	获取未来7天内到期的任务	无
`get_overdue_tasks`	获取所有逾期任务	无
`get_tasks_and_events_for_date`	获取特定日期的任务和事件	`iso_date_with_timezone`

注：这 get_tasks_and_events_for_date 该工具与谷歌日历集成，在TickTick任务旁边显示您的日历事件。这需要设置Google日历身份验证（请参阅上面的Google日历身份认证部分）。

完成工作（GTD）框架

工具	说明	参数
`batch_create_tasks`	一次创建多个任务	`tasks` （任务字典列表）

实用工具

工具	说明	参数
`get_current_time_in_users_timezone`	获取用户配置的时区中的当前时间	无

克劳德提示示例

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

将军

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

任务筛选查询

“我今天有什么任务要交？”
“让我看看所有过期的东西”
“显示本周到期的所有任务”
“显示我今天的任务和事件”
“搜索有关‘project alpha’的任务”
“显示标题或描述中带有“客户端”的所有任务”
“显示我的所有高优先级任务”

GTD工作流程

遵循David Allen的“完成任务”框架，管理参与度和下一步行动。

Engaged将检索今天到期或逾期的高优先级任务。
Next将检索中等优先级或明天到期。
使用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流程：

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

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

贡献

欢迎投稿！请随时提交拉取请求。

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。