Things MCP Server

Things MCP 服务器

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

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

为什么选择 Things MCP？

此 MCP 服务器为您的任务管理释放了 AI 的力量：

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

特征

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

安装选项

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

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

先决条件

• Python 3.12+
• 克劳德桌面
• Things 3（必须在“设置”->“通用”中打开“启用 Things URL”）

安装

或者使用 uv (推荐):

跑步

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

选项 2：手动安装

先决条件

• Python 3.12+
• 克劳德桌面
• Things 3（必须在“设置”->“通用”中打开“启用 Things URL”）

步骤1：安装uv

如果尚未安装 uv，请安装：

然后重新启动您的终端。

第 2 步：克隆此存储库

步骤 3：设置 Python 环境和依赖项

步骤 4：配置 Things 身份验证令牌

运行配置工具来设置您的 Things 身份验证令牌：

这将指导您完成配置 Things 身份验证令牌的过程，这是 MCP 服务器与您的 Things 应用程序交互所必需的。

步骤5：配置Claude桌面

编辑Claude桌面配置文件：

将 Things 服务器添加到配置文件中的 mcpServers 键（确保更新安装这些文件的文件夹的路径）：

步骤6：重启Claude Desktop

重新启动 Claude Desktop 应用程序以应用更改。

Claude Desktop 的使用示例

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

尖端

• 在 Claude 中创建一个项目，其中包含自定义说明，解释如何使用 Things 以及组织区域、项目、标签等。告诉 Claude 创建新任务时您希望包含哪些信息（例如，要求它在任务描述中包含相关详细信息可能会有所帮助）。
• 尝试添加另一个允许 Claude 访问您日历的 MCP 服务器。这样您就可以让 Claude 在日历上为特定任务预留时间，根据即将发生的日历事件（例如会议准备）创建待办事项等等。

可用工具

列表视图

• get-inbox - 从收件箱获取待办事项
• get-today - 获取今天到期的待办事项
• get-upcoming - 获取即将发生的待办事项
• get-anytime - 从 Anytime 列表中获取待办事项
• get-someday - 从 Someday 列表中获取待办事项
• get-logbook - 获取已完成的待办事项
• get-trash - 获取已删除的待办事项

基本操作

• get-todos - 获取待办事项，可选择按项目进行过滤
• get-projects - 获取所有项目
• get-areas - 获取所有区域

标签操作

• get-tags获取所有标签
• get-tagged-items - 获取带有特定标签的项目

搜索行动

• search-todos - 按标题/注释进行简单搜索
• search-advanced - 具有多个过滤器的高级搜索

基于时间的操作

• get-recent - 获取最近创建的项目

工具参数

待办事项

• 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”、“1y”）

添加待办事项

• title - 待办事项的标题
• notes （可选）- 待办事项的注释
• when （可选）- 何时安排待办事项（今天、明天、晚上、任何时间、某一天或 YYYY-MM-DD）
• deadline （可选）- 待办事项的截止日期（YYYY-MM-DD）
• tags （可选） - 应用于待办事项的标签
• list_title或list_id (可选) - 要添加的项目/区域的标题或 ID
• heading （可选）- 添加标题
• checklist_items （可选）- 要添加的清单项目

更新待办事项

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

添加项目

• title - 项目标题
• notes （可选）- 项目注释
• when （可选）- 何时安排项目
• deadline （可选）- 项目截止日期
• tags （可选） - 应用于项目的标签
• area_title或area_id （可选）- 要添加的区域的标题或 ID
• todos （可选）- 项目中要创建的初始 todos

更新项目

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

显示项目

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

身份验证令牌配置

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

如何获取 Things 身份验证令牌

1. 在 Mac 上打开 Things 应用
2. 前往 Things → Preferences (⌘,)
3. 选择常规选项卡
4. 确保选中“启用 Things URL”
5. 查找首选项窗口中显示的身份验证令牌

配置令牌

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

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

发展

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

实施选项

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

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

开发工作流程

设置开发环境

在开发过程中测试更改

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

为 PyPI 构建包

发布到 PyPI

需要 Python 3.12+。

故障排除

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

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

常见问题

1. 令牌缺失或无效：运行python configure_token.py来设置您的令牌
2. Things 应用程序未运行：使用 MCP 服务器时，请确保 Things 3 处于打开状态
3. URL 方案未启用：检查 Things → Preferences → General 中的“启用 Things URL”是否已启用

检查日志

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