MCP服务器
这 模型上下文协议（MCP） 服务器允许您使用Claude Desktop与中的任务管理数据进行交互 Things应用程序。您可以要求Claude创建任务、分析项目、帮助管理优先级等。
- 稳健的错误处理 具有指数退避和重试机制
- 断路器型式 防止级联故障
- 死信队列 对于失败的操作
- 智能缓存 为了提高性能
- 综合录井 具有结构化JSON输出
- AppleScript桥 对于URL方案失败的操作
- 速率限制 以防止淹没Things应用程序
- 广泛的测试套件 可靠性
为什么是MCP？
此MCP服务器为您的任务管理解锁了AI的力量：
- 自然语言任务创建：让克劳德用自然语言创建包含所有细节的任务
- 智能任务分析：深入了解您的项目和生产力模式
- GTD和生产力工作流程：让Claude帮助您实施生产力系统
- 无缝集成：直接使用现有的Things 3数据
特性
- 访问所有主要事项列表（收件箱、今天、即将到来等）
- 项目和区域管理
- 标签操作
- 高级搜索功能
- 最近的项目跟踪
- 详细的项目信息，包括检查表
- 支持嵌套数据（区域内的项目，项目内的待办事项）
安装选项
有多种方法可以安装和使用Things MCP服务器：
选项1：从PyPI安装（推荐）
先决条件
- Python 3.12+
- 克劳德桌面
- 事情3（必须在设置->常规中打开“启用事情URL”）
- Things身份验证令牌（URL方案操作所需）
安装
pip install things-mcp或使用紫外线（推荐）：
uv pip install things-mcp跑步
安装后，您可以直接运行服务器：
things-mcp选项2：手动安装
先决条件
- Python 3.12+
- 克劳德桌面
- 事情3（必须在设置->常规中打开“启用事情URL”）
第一步：安装uv
如果您还没有安装uv：
curl -LsSf https://astral.sh/uv/install.sh | sh之后重新启动终端。
步骤2：克隆此存储库
git clone https://github.com/hald/things-mcp
cd things-mcp步骤3：设置Python环境和依赖关系
uv venv
uv pip install -r pyproject.toml步骤4：配置Things身份验证令牌
运行配置工具设置Things身份验证令牌：
python configure_token.py这将指导您完成配置Things身份验证令牌的过程，这是MCP服务器与Things应用程序交互所必需的。
步骤5：配置Claude桌面
编辑Claude Desktop配置文件：
code ~/Library/Application\ Support/Claude/claude_desktop_config.json将Things服务器添加到配置文件中的mcpServers密钥中（确保更新安装这些文件的文件夹的路径）：
{
"mcpServers": {
"things": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",
"run",
"things_server.py"
]
}
}
}步骤6：配置身份验证令牌
Things URL方案需要身份验证令牌。你可以在Things中找到它→ 设置→ 将军。
选项1：通过配置脚本设置
python configure_token.py选项2：通过环境变量设置
export THINGS_AUTH_TOKEN="your-token-here"选项3：手动创建配置文件
mkdir -p ~/.things-mcp
echo '{"things_auth_token": "your-token-here"}' > ~/.things-mcp/config.json步骤7：重新启动克劳德桌面
重新启动Claude Desktop应用程序以应用更改。
Claude Desktop使用示例
- “我今天的待办事项清单上有什么？”
- “为下周的海滩度假制定一个待办事项，包括一份打包清单。”
- “使用艾森豪威尔矩阵评估我当前的待办事项。”
- “帮助我使用Things进行GTD风格的每周回顾。”
提示
- 使用自定义说明在Claude中创建一个项目，解释如何使用Things并组织区域、项目、标签等。告诉克劳德，当它创建新任务时，你希望包含哪些信息（例如，要求它在任务描述中包含相关细节可能会有所帮助）。
- 尝试添加另一个MCP服务器，让Claude访问您的日历。这将允许你让克劳德在日历上为特定任务留出时间，根据即将到来的日历事件创建待办事项（例如为会议做准备）等。
可用工具
列表视图
get-inbox-从收件箱获取待办事项get-today-获得今天到期的待办事项get-upcoming-获取即将到来的待办事项get-anytime-从Anytime列表中获取待办事项get-someday-从某一天列表中获取待办事项get-logbook-完成待办事项get-trash-收到垃圾待办事项
基本操作
get-todos-获取待办事项，可选择按项目筛选get-projects-获取所有项目get-areas-获取所有区域
标签操作
get-tags-获取所有标签get-tagged-items-获取具有特定标签的项目
搜索操作
search-todos-按标题/注释进行简单搜索search-advanced-具有多个过滤器的高级搜索
基于时间的操作
get-recent-获取最近创建的项目
修改操作
add-todo-创建具有完整参数支持的新todoadd-project-使用标签和待办事项创建新项目update-todo-更新现有待办事项update-project-更新现有项目delete-todo-删除待办事项（移至垃圾箱）delete-project-删除项目（移至回收站）show-item-在Things中显示特定项目或列表search-items-在Things中搜索项目
刀具参数
get-所有
project_uuid（可选）-按项目筛选待办事项include_items（可选，默认值：true）-包括检查表项目
获取项目/获取区域/获取标签
include_items（可选，默认值：false）-包括包含的项目
搜索高级
status-按状态筛选（未完成/已完成/已取消）start_date-按开始日期（YYYY-MM-DD）筛选deadline-按截止日期筛选（YYYY-MM-DD）tag-按标签筛选area-按区域UUID筛选type-按项目类型（待办事项/项目/标题）筛选
获取最新信息
period-时间段（例如，“3d”、“1w”、“2m”、“1年”）
添加所有
title-todo的标题notes（可选）-待办事项注释when（可选）-何时安排待办事项（今天、明天、晚上、任何时候、某天或YYYY-MM-DD）deadline（可选）-待办事项的截止日期（YYYY-MM-DD）tags（可选）-应用于todo的标签list_title或list_id（可选）-要添加的项目/区域的标题或IDheading（可选）-添加标题checklist_items（可选）-要添加的清单项目
更新待办事项
id-要更新的待办事项的IDtitle（可选）-新标题notes（可选）-新注释when（可选）-新时间表deadline（可选）-新的截止日期tags（可选）-新标签completed（可选）-标记为已完成canceled（可选）-标记为已取消
添加项目
title-项目名称notes（可选）-项目注释when（可选）-何时安排项目deadline（可选）-项目截止日期tags（可选）-应用于项目的标签area_title或area_id（可选）-要添加的区域的标题或IDtodos（可选）-在项目中创建的初始待办事项
更新项目
id-要更新的项目的IDtitle（可选）-新标题notes（可选）-新注释when（可选）-新时间表deadline（可选）-新的截止日期tags（可选）-新标签completed（可选）-标记为已完成canceled（可选）-标记为已取消
删除待办事项
id-要删除的待办事项的ID（移动到垃圾箱）
删除项目
id-要删除的项目的ID（移动到回收站）
显示项目
id-要显示的项目ID，或以下之一：收件箱、今天、即将到来、任何时候、某一天、日志query（可选）-可选查询以进行筛选filter_tags（可选）-可选的筛选标签
重要限制
标签
- 标签必须存在于Things中，然后才能应用于待办事项或项目
- 当您尝试使用缺失的标签时，MCP服务器会自动创建这些标签
- 如果标签创建失败，todo/项目仍将被创建，但没有标签
认证凭证
- 所有URL方案操作（创建、更新、删除）都需要
- 如果没有令牌，Things将在每次操作时提示进行身份验证
身份验证令牌配置
Things MCP服务器需要一个身份验证令牌才能与Things应用程序交互。此令牌用于授权URL方案命令。
如何获取Things身份验证令牌
- 在Mac上打开Things应用程序
- 转到事物→ 首选项（⌘，）
- 选择“常规”选项卡
- 确保选中“启用事物URL”
- 查找首选项窗口中显示的身份验证令牌
配置令牌
运行附带的配置工具来设置您的令牌：
python configure_token.py此交互式脚本将提示您输入令牌，并将其安全地保存在本地配置中。
发展
此项目使用 pyproject.toml 管理依赖关系和构建配置。它是使用 模型上下文协议，这允许克劳德安全地访问工具和数据。
实施方案
该项目提供了两种不同的实施方法：
- 标准MCP服务器 (
things_server.py)-使用基本MCP服务器模式的原始实现。
- FastMCP服务器 (
things_fast_server.py)-使用FastMCP模式的现代实现，通过基于装饰器的工具注册，实现更清晰、更可维护的代码。
开发工作流程
建立开发环境
# Clone the repository
git clone https://github.com/hald/things-mcp
cd things-mcp
# Set up a virtual environment with development dependencies
uv venv
uv pip install -e ".[dev]" # Install in development mode with extra dependencies测试开发过程中的更改
使用MCP开发服务器测试更改：
# Test the FastMCP implementation
mcp dev things_fast_server.py
# Or test the traditional implementation
mcp dev things_server.py为PyPI构建包
python -m build发布到PyPI
twine upload dist/*需要Python 3.12以上。
可靠性特征
错误处理和恢复
- 重试逻辑：针对暂时性故障，采用指数回退自动重试
- 断路器：防止重复故障使系统不堪重负
- 死信队列：存储失败的操作以供以后重试或分析
- AppleScript回退：当URL方案操作失败时，回退到直接AppleScript
性能优化
- 智能缓存：使用适当的TTL缓存频繁访问的数据
- 速率限制：防止过多请求使Things应用程序不堪重负
- 缓存失效：修改数据时自动清除缓存
监控与调试
- 结构化日志记录：JSON格式的日志，以便更好地分析
- 运营跟踪：每个操作都记录了时间和状态
- 缓存统计：使用监视缓存性能
get-cache-stats工具 - 日志位置:
- 主要日志： ~/.things-mcp/logs/things_mcp.log - 结构化日志： ~/.things-mcp/logs/things_mcp_structured.json - 错误日志： ~/.things-mcp/logs/things_mcp_errors.log
故障排除
服务器包括以下错误处理：
- UUID无效
- 缺少必要参数
- Things数据库访问错误
- 数据格式错误
- 身份验证令牌问题
- 网络超时
- AppleScript执行失败
常见问题
- 令牌丢失或无效：运行
python configure_token.py设置您的令牌 - Things应用程序未运行：服务器将尝试自动启动Things
- URL方案未启用：检查Things中是否启用了“启用Things URL”→ 偏好设置→ 将军
- 操作失败：检查断路器状态和死信队列
- 性能问题：使用监视缓存统计信息
get-cache-stats工具
检查日志
所有错误都会被记录并返回描述性消息。查看MCP日志：
# Follow main logs in real-time
tail -f ~/.things-mcp/logs/things_mcp.log
# Check error logs
tail -f ~/.things-mcp/logs/things_mcp_errors.log
# View structured logs for analysis
cat ~/.things-mcp/logs/things_mcp_structured.json | jq
# Claude Desktop MCP logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log高级调试
- 检查死信队列：失败的操作存储在
things_dlq.json - 监控断路器：在日志中查找“断路器”消息
- 高速缓存性能：使用
get-cache-stats检查命中率的工具 - 启用调试日志记录：在中设置控制台级别为DEBUG
logging_config.py