Things MCP 服务器

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

该服务器利用了 Things.py 库和 Things URL Scheme。

为什么选择 Things MCP？

这个 MCP 服务器为你的任务管理解锁了 AI 的力量：

• 自然语言任务创建：使用自然语言让 Claude 创建包含所有细节的任务
• 智能任务分析：深入了解你的项目和生产力模式
• GTD 和生产力工作流：让 Claude 帮助你实施生产力系统
• 无缝集成：直接与你现有的 Things 3 数据协同工作

功能

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

安装选项

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

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

先决条件

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

安装

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 应用交互所必需的。

步骤 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：重启 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 - 获取最近创建的条目

工具参数

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 (可选) - 标记为已取消

show-item

• id - 要显示的项目的ID，或者可以是：inbox, today, upcoming, anytime, someday, logbook
• query (可选) - 可选的查询条件
• filter_tags (可选) - 可选的过滤标签

认证令牌配置

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

如何获取您的Things认证令牌

1. 在Mac上打开Things应用程序
2. 前往 Things → 首选项 (⌘,)
3. 选择“常规”选项卡
4. 确保勾选了“启用Things URL”
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+。

故障排除

服务器包括以下错误处理：

• 无效的UUID
• 缺少必需参数
• Things数据库访问错误
• 数据格式错误
• 认证令牌问题

常见问题

1. 缺少或无效的令牌：运行python configure_token.py来设置您的令牌
2. Things应用程序未运行：确保在使用MCP服务器时Things 3是打开状态
3. 未启用URL方案：检查“启用Things URL”是否已在Things → 首选项 → 常规中启用

检查日志

所有错误都会被记录并附带描述性消息返回。要从 Claude Desktop 查看 MCP 日志，请在终端中运行以下命令：

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log