Things MCP Server

Things MCP 服务

这个 Model Context Protocol (MCP) 服务可让你使用 Claude Desktop 与 Things app 中的任务管理数据交互。你可以让 Claude 创建任务、分析项目、协助管理优先级等。

此服务使用 Things.py 库和 Things URL Scheme，并提供额外的可靠性功能，包括：

• 稳健的错误处理，支持指数退避和重试机制
• 熔断器模式，防止故障级联
• 死信队列，用于存放失败的操作
• 智能缓存，提升性能
• 全面的日志记录，采用结构化 JSON 输出
• AppleScript 桥接，用于处理通过 URL scheme 失败的操作
• 速率限制，防止 Things app 不堪重负
• 全面的测试套件，确保可靠性

为什么选择 Things MCP？

此 MCP 服务为任务管理解锁 AI 的强大能力：

• 自然语言创建任务：用自然语言让 Claude 创建包含所有详细信息的任务
• 智能任务分析：洞察你的项目和效率模式
• GTD 与效率工作流：让 Claude 协助你实施效率系统
• 无缝集成：直接使用你现有的 Things 3 数据

功能

• 访问所有主要的 Things 列表（收件箱、今天、即将到来等）
• 项目和领域管理
• 标签操作
• 高级搜索功能
• 最近项目跟踪
• 包含检查清单在内的详细项目资料
• 支持嵌套数据（领域中的项目、项目中的待办事项）

安装选项

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

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

先决条件

• Python 3.12+
• Claude Desktop
• Things 3（必须在“设置”->“通用”中启用“Enable Things URLs”）
• Things 身份验证令牌（URL scheme 操作所必需）

安装

pip install things-mcp

或使用 uv（推荐）：

uv pip install things-mcp

运行

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

things-mcp

选项 2：手动安装

先决条件

• Python 3.12+
• Claude Desktop
• Things 3（必须在“设置”->“通用”中启用“Enable 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 app 交互。

第 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 scheme 需要身份验证令牌。你可以在 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 创建新任务时需要包含哪些信息（例如，让它在任务描述中加入相关详情可能会有所帮助）。
• 尝试添加另一个能让 Claude 访问日历的 MCP 服务。这样你就可以让 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，或以下其中一项：inbox、today、upcoming、anytime、someday、logbook
• query（可选）- 用于筛选的可选查询
• filter_tags（可选）- 用于筛选的可选标签

重要限制

标签

• 标签必须先存在于 Things 中，才能应用到待办事项或项目
• 尝试使用不存在的标签时，MCP 服务会自动创建这些标签
• 如果创建标签失败，待办事项／项目仍会创建，但不会带有标签

身份验证令牌

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

身份验证令牌配置

Things MCP 服务需要身份验证令牌才能与 Things 应用交互。此令牌用于授权 URL scheme 命令。

如何获取 Things 身份验证令牌

1. 在 Mac 上打开 Things 应用
2. 前往 Things → Preferences（⌘,）
3. 选择 General 标签页
4. 确保勾选了 “Enable Things URLs”
5. 在偏好设置窗口中查找显示的身份验证令牌

配置令牌

运行随附的配置工具来设置令牌：

python configure_token.py

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

开发

此项目使用 pyproject.toml 管理依赖项和构建配置。它基于 Model Context Protocol 构建，使 Claude 能够安全地访问工具和数据。

实现方案

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

1. 标准 MCP 服务（things_server.py）- 使用基本 MCP 服务模式的原始实现。

2. 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 scheme 操作失败时，回退到直接使用 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 → Preferences → General 中是否启用了“Enable Things URLs”
4. 操作失败：检查熔断器状态和死信队列
5. 性能问题：使用 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

高级调试

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