JinDaGe - Things App MCP Details

article

README

🚀 事项 MCP 服务器

这个模型上下文协议 (MCP) 服务器可让你借助 Claude 桌面版，与 Things 应用中的任务管理数据进行交互。你能让 Claude 创建任务、分析项目、协助管理优先级等。

该服务器借助了 Things.py 库和 Things URL 方案。

🚀 快速开始

此服务器能让你使用 Claude 桌面版与 Things 应用中的任务管理数据交互，实现创建任务、分析项目等功能。

✨ 主要特性

可访问所有主要的 Things 列表（收件箱、今天、即将进行等）
支持项目和领域管理
能进行标签操作
具备高级搜索功能
可跟踪最近项目
提供详细的任务信息，包括检查列表
支持嵌套数据（领域中的项目、项目中的待办事项）

📦 安装指南

适用于 Claude 桌面版

先决条件
- Python 3.12+
- Claude 桌面版
- Things 3 （“启用 Things URLs” 必须在设置 -> 通用中打开）
若尚未安装，安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

重新启动终端。 3. 克隆此仓库：

git clone https://github.com/hald/things-mcp

安装所需的 Python 包：

cd things-mcp
uv venv
uv pip install -r pyproject.toml

编辑 Claude 桌面版配置文件：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

在 JSON 数组中添加以下内容：

{
  "mcpEndpoints": [
    {
      "name": "Things",
      "url": "http://localhost:9001"
    }
  ]
}

💻 使用示例

基础用法

提供一些在 Claude 桌面版中使用该服务器的示例问题：

列出所有项目和待办事项。
创建新的任务或项目。
根据截止日期筛选任务。
更新现有任务的状态或属性。

小贴士

⚠️ 重要提示

该服务器包括对以下错误的处理：无效的 UUID、缺少必填参数、Things 数据库访问错误、数据格式错误。所有错误都会记录并带有描述性消息返回。

💡 使用建议

在设置中启用 Things 数据库的日志记录，以便更好地调试和监控：

defaults write com.culturedcode.Things-MacOS developer-mode -bool true

使用 poetry run 命令运行服务器以隔离依赖项环境。

📚 详细文档

可用工具

查询工具

/items
获取 Things 数据库中的所有项目和待办事项。支持分页加载更多数据。

创建工具

/items/create
在 Things 中创建新的任务或项目。

更新工具

/items/update
更新现有任务或项目的属性和状态。

工具参数

查询工具 (/items)

| 属性 | 详情 | |------|------| | 参数名称 | cursor、include_archived | | 类型 | String、Boolean | | 描述 | 分页游标，用于获取更多数据；是否包含已存档的项目和待办事项。 |

创建工具 (/items/create)

| 属性 | 详情 | |------|------| | 参数名称 | title、type、due_date | | 类型 | String、String、Date | | 描述 | 新任务或项目的标题；项目类型，可选值：'to-do' 或 'project'；任务的截止日期（ISO 格式）。 |

更新工具 (/items/update)

| 属性 | 详情 | |------|------| | 参数名称 | item_id、title、status | | 类型 | String、String、String | | 描述 | 要更新的任务或项目的唯一标识符；新标题，可选；新状态，可选值：'not-started', 'in-progress', 'completed'。 |

故障排除

要查看 Claude 桌面版的 MCP 日志，请在终端中运行：

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

Things App