Things MCP Server

此 模型上下文协议 (MCP) 服务器允许您使用 Claude Desktop 与 Things 应用中的任务管理数据进行交互。您可以请求 Claude 创建任务、分析项目、帮助管理优先级等。

该服务器利用了 Things.py 库和 Things URL 方案，并具有以下额外的可靠性特性：

• 强大的错误处理，包括指数退避和重试机制
• 断路器模式，以防止级联故障
• 死信队列，用于存储失败的操作
• 智能缓存，以提高性能
• 全面的日志记录，带有结构化的 JSON 输出
• AppleScript 桥接，用于 URL 方案操作失败的情况
• 速率限制，以防止对 Things 应用造成过载
• 广泛的测试套件，确保可靠性

为什么选择 Things MCP？

这个 MCP 服务器解锁了 AI 在任务管理中的强大功能：

• 自然语言任务创建：请求 Claude 使用自然语言创建任务
• 智能任务分析：获取关于您的项目的洞察力和生产力模式
• GTD 和生产力工作流：让 Claude 帮助您实施生产力系统
• 无缝集成：直接与您现有的 Things 3 数据集成

功能

• 访问 Things 的主要列表（收件箱、今天、即将到来等）
• 项目和区域管理
• 标签操作
• 高级搜索能力
• 最近项目的跟踪
• 详细的项目信息，包括检查清单
• 支持嵌套数据（区域内的项目，项目内的待办事项）

安装选项

有多种方式安装和使用 Things MCP 服务器：

选项 1：从 PyPI 安装（推荐）

先决条件

• Python 3.12+
• Claude Desktop
• Things 3（必须在设置 -> 通用中启用 Things URLs）
• Things 认证令牌（用于 URL 方案操作）

安装

pip install things-mcp

或者使用 uv（推荐）：

uv pip install things-mcp

运行

安装后，可以直接运行服务器：

things-mcp

选项 2：手动安装

先决条件

• Python 3.12+
• Claude Desktop
• Things 3（必须在设置 -> 通用中启用 Things URLs）

步骤 1：安装 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 Desktop

编辑 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 应用以应用更改。

使用 Claude Desktop 的示例

• “今天我的待办事项是什么？”
• “创建一个待办事项，为下周的海滩度假打包，包括打包清单。”
• “使用艾森豪威尔矩阵评估我当前的待办事项。”
• “帮我使用 Things 进行 GTD 风格的每周回顾。”

提示

• 在 Claude 中创建一个项目，附带自定义说明，解释您如何使用 Things 并组织区域、项目、标签等。告诉 Claude 在创建新任务时希望包含哪些信息（例如，要求它在任务描述中包含相关细节可能会有所帮助）。
• 尝试添加另一个 MCP 服务器，使 Claude 能够访问您的日历。这样，您可以请求 Claude 为您安排特定任务的时间，从即将来临的日历事件创建待办事项（例如，为会议做准备）等。

可用工具

列表视图

• get-inbox - 获取收件箱中的待办事项
• get-today - 获取今天到期的待办事项
• get-upcoming - 获取即将到来的待办事项
• get-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 - 创建一个新的待办事项，支持完整的参数
• add-project - 创建一个新的项目，带有标签和待办事项
• update-todo - 更新现有的待办事项
• update-project - 更新现有的项目
• delete-todo - 删除待办事项（移动到回收站）
• delete-project - 删除项目（移动到回收站）
• show-item - 显示 Things 中的具体项目或列表
• search-items - 在 Things 中搜索项目

工具参数

get-todos

• project_uuid（可选）- 按项目过滤待办事项
• include_items（可选，默认值：true）- 包含检查清单项目

get-projects / get-areas / get-tags

• include_items（可选，默认值：false）- 包含包含的项目

search-advanced

• status - 按状态过滤（未完成/已完成/已取消）
• start_date - 按开始日期过滤（YYYY-MM-DD）
• deadline - 按截止日期过滤（YYYY-MM-DD）
• tag - 按标签过滤
• area - 按区域 UUID 过滤
• type - 按项目类型过滤（待办事项/项目/标题）

get-recent

• period - 时间周期（例如，'3d'，'1w'，'2m'，'1y'）

add-todo

• title - 待办事项的标题
• notes（可选）- 待办事项的备注
• when（可选）- 调度待办事项的时间（今天、明天、晚上、任意时间、某天，或 YYYY-MM-DD）
• deadline（可选）- 待办事项的截止日期（YYYY-MM-DD）
• tags（可选）- 应用于待办事项的标签
• list_title 或 list_id（可选）- 添加到的项目/区域的标题或 ID
• heading（可选）- 添加到的标题下
• checklist_items（可选）- 添加的检查清单项目

update-todo

• id - 要更新的待办事项的 ID
• title（可选）- 新标题
• notes（可选）- 新备注
• when（可选）- 新调度
• deadline（可选）- 新截止日期
• tags（可选）- 新标签
• completed（可选）- 标记为已完成
• canceled（可选）- 标记为已取消

add-project

• title - 项目的标题
• notes（可选）- 项目的备注
• when（可选）- 调度项目的时间
• deadline（可选）- 项目的截止日期
• tags（可选）- 应用于项目的标签
• area_title 或 area_id（可选）- 添加到的区域的标题或 ID
• todos（可选）- 在项目中创建的初始待办事项

update-project

• id - 要更新的项目的 ID
• title（可选）- 新标题
• notes（可选）- 新备注
• when（可选）- 新调度
• deadline（可选）- 新截止日期
• tags（可选）- 新标签
• completed（可选）- 标记为已完成
• canceled（可选）- 标记为已取消

delete-todo

• id - 要删除的待办事项的 ID（移动到回收站）

delete-project

• id - 要删除的项目的 ID（移动到回收站）

show-item

• id - 要显示的项目的 ID，或其中之一：收件箱、今天、即将到来、任意时间、某天、日志簿
• query（可选）- 可选查询以过滤
• filter_tags（可选）- 可选标签以过滤

重要限制

标签

• 标签必须在 Things 中存在才能应用于待办事项或项目
• MCP 服务器会在您尝试使用它们时自动创建缺失的标签
• 如果标签创建失败，待办事项/项目仍会被创建但没有标签

认证令牌

• 所有 URL 方案操作（创建、更新、删除）都需要
• 没有令牌，Things 将在每次操作时提示进行身份验证

认证令牌配置

Things MCP 服务器需要一个认证令牌来与 Things 应用交互。此令牌用于授权 URL 方案命令。

如何获取您的 Things 认证令牌

1. 在 Mac 上打开 Things 应用
2. 转到 Things → 首选项（⌘,）
3. 选择常规标签
4. 确保“启用 Things URLs”被勾选
5. 查看首选项窗口中显示的认证令牌

配置令牌

运行包含的配置工具来设置您的令牌：

python configure_token.py

此交互式脚本会提示您输入令牌，并将其安全地保存在本地配置中。

开发

此项目使用 pyproject.toml 来管理依赖项和构建配置。它是使用 模型上下文协议 构建的，允许 Claude 安全地访问工具和数据。

实现选项

此项目提供了两种不同的实现方法：

1. 标准 MCP 服务器（things_server.py）- 原始实现，使用基本的 MCP 服务器模式。
2. FastMCP 服务器（things_fast_server.py）- 使用 FastMCP 模式的现代实现，具有基于装饰器的工具注册，代码更简洁且易于维护。

开发流程

设置开发环境

# 克隆仓库
git clone https://github.com/hald/things-mcp
cd things-mcp

# 设置带有开发依赖项的虚拟环境
uv venv
uv pip install -e ".[dev]"  # 以开发模式安装，带有额外依赖项

开发期间测试更改

使用 MCP 开发服务器测试更改：

# 测试 FastMCP 实现
mcp dev things_fast_server.py

# 或测试传统实现
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 执行失败

常见问题

1. 缺少或无效的令牌：运行 python configure_token.py 来设置您的令牌
2. Things 应用未运行：服务器将尝试自动启动 Things
3. URL 方案未启用：检查 Things → 首选项 → 通用中是否启用了 Things URLs
4. 操作失败：检查断路器状态和死信队列
5. 性能问题：使用 get-cache-stats 工具监控缓存统计

查看日志

所有错误都被记录并返回带有描述性消息。要查看 MCP 日志：

# 实时跟随主日志
tail -f ~/.things-mcp/logs/things_mcp.log

# 检查错误日志
tail -f ~/.things-mcp/logs/things_mcp_errors.log

# 查看结构化日志进行分析
cat ~/.things-mcp/logs/things_mcp_structured.json | jq

# Claude Desktop MCP 日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

高级调试

1. 检查死信队列：失败的操作存储在 things_dlq.json
2. 监控断路器：在日志中查找“断路器”消息
3. 缓存性能：使用 get-cache-stats 工具检查命中率
4. 启用调试日志：在 logging_config.py 中将控制台级别设置为 DEBUG