Things MCP 服务器

这个 模型上下文协议 (MCP) 服务器让你使用 Claude Desktop 与你在 Things app 中的任务管理数据进行交互。你可以让 Claude 创建任务、分析项目、帮助管理优先级等等。

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

<a href="https://glama.ai/mcp/servers/t9cgixg2ah"><img width="380" height="200" src="https://glama.ai/mcp/servers/t9cgixg2ah/badge" alt="Things Server MCP server" /></a>

为什么选择 Things MCP？

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

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

功能

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

安装选项

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

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

前提条件

• Python 3.12+
• Claude Desktop
• Things 3（必须在“设置 -> 常规”中启用“启用 Things URL”）

安装

pip install things-mcp

或者使用 uv (推荐):

uv pip install things-mcp

运行

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

things-mcp

选项 2：手动安装

前提条件

• Python 3.12+
• Claude Desktop
• Things 3（必须在“设置 -> 常规”中启用“启用 Things URL”）

步骤 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 来管理依赖项和构建配置。它使用 模型上下文协议 构建，该协议允许 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+。

故障排除

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

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

常见问题

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

检查日志

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

# 实时跟踪日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log