星战科技xingzhan.cloud
返回市场
物联-MCP

物联-MCP

作者：hald162 星标更新：2025-09-11
安装使用来源：spider==github.com

项目介绍

Things MCP Server

此模型上下文协议（MCP）服务器允许您使用Claude Desktop与来自Cultured Code的Things 3任务管理数据进行交互。您可以要求Claude创建任务、分析项目、帮助管理优先级等。

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

<a href="https://glama.ai/mcp/servers/t9cgixg2ah"><img width="380" height="200" src="https://gips3.baidu.com/it/u=903968790,3060702876&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Things Server MCP server" /></a>

支持该项目

如果您发现这个项目有用，请考虑支持其开发：

ko-fi

功能

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

安装

先决条件

  • macOS（Things 3仅适用于Mac）
  • 一个MCP客户端，如Claude Desktop或Claude Code
  • Things 3应用并开启“启用Things URL”（设置 → 通用）

DXT安装（推荐用于Claude Desktop）

桌面扩展(.dxt)提供了最简单的MCP服务器安装方式。

  1. 从发布页面下载最新的things-mcp-0.4.0.dxt文件
  2. 双击.dxt文件以在Claude Desktop中安装它
  3. 扩展会自动配置并准备好使用

就这样！DXT包包括所有Python依赖项，并自动处理配置。

要使用Claude Code或其他MCP客户端设置Things MCP，请滚动到手动安装部分。

验证是否工作

安装后：

  • 如果使用Claude Desktop，您应该能在“搜索和工具”列表中看到“Things MCP”
  • 尝试询问：“我的Things收件箱里有什么？”

使用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 - 获取最近创建的项目

Things URL Scheme操作

  • add-todo - 创建新的待办事项
  • add-project - 创建新的项目
  • update-todo - 更新现有的待办事项
  • update-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'）

手动安装

对于偏好从源代码安装的高级用户：

第一步：安装uv（Python包管理器）

首先，确保已安装Homebrew：

# 检查是否已安装Homebrew
brew --version

# 如果未安装，安装Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

然后安装uv（如果尚未安装）：

brew install uv

第二步：克隆仓库

选择一个您想要安装Things MCP的位置。例如，要在您的主目录中安装：

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

重要：记住这个位置！您需要完整的路径。可以通过运行以下命令获取：

pwd

这将显示类似这样的内容：/Users/yourusername/things-mcp

第三步：安装依赖项

uv sync

第四步：配置Claude

对于Claude Desktop：

  1. 打开Claude Desktop
  2. 转到Claude → 设置 → 开发者 → 编辑配置
  3. 在mcpServers部分添加Things服务器：
{
  "mcpServers": {
    "things": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/yourusername/things-mcp",
        "run",
        "things_server.py"
      ]
    }
  }
}

替换/Users/yourusername/things-mcp为第二步中的实际路径！

注意：如果您使用的是Homebrew之外安装的uv，您可能需要在MCP配置中使用uv的完整路径。常见位置包括：

  • pip安装：通常在您的Python环境的bin目录下
  • 独立安装程序：~/.local/bin/uv 或 ~/.cargo/bin/uv

要找到您的uv位置，运行：

which uv
  1. 保存文件并重新启动Claude Desktop

对于Claude Code：

在您的终端中运行：

claude mcp add-json things '{"command":"uv","args":["--directory","/path/to/things-mcp","run","things_server.py"]}'

替换/path/to/things-mcp为第二步中的实际路径！

要使其全局可用（跨所有项目），添加-s user：

claude mcp add-json -s user things '{"command":"uv","args":["--directory","/path/to/things-mcp","run","things_server.py"]}'

第五步：验证是否工作

重启您的MCP客户端后：

  • 如果使用Claude Desktop，您应该能在“搜索和工具”列表中看到“Things 3”
  • 尝试询问：“我的Things收件箱里有什么？”

故障排除

如果不起作用：

  1. 确保已安装Things 3并且至少打开过一次

    • Things数据库需要存在才能让服务器工作

  2. 检查是否开启了“启用Things URL”

    • 打开Things → 设置 → 通用 → 启用Things URL

  3. 验证配置中的路径与您克隆仓库的位置匹配

    • 路径必须是绝对路径（以/开头）
    • 在things-mcp目录中运行pwd以获取正确的路径

  4. 检查Claude的日志是否有错误：

    tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

  5. 常见问题：

    • “无法附加到MCP” - 通常意味着路径错误
    • “spawn uv ENOENT” - 确保使用Homebrew安装了uv（brew install uv）
    • “没有名为'things'的模块” - 在things-mcp目录中运行uv sync
    • “命令未找到：uv” - 使用Homebrew安装uv：brew install uv

更新

要更新到最新版本：

cd ~/things-mcp  # 或者您安装它的任何地方
git pull
uv sync

然后重启Claude。

开发

运行测试

该项目包括针对URL方案和格式化模块的全面单元测试套件。

# 安装测试依赖项
uv sync --extra test

# 运行所有测试
uv run pytest

# 运行带有详细输出的测试
uv run pytest -v

# 运行特定的测试文件
uv run pytest tests/test_url_scheme.py

# 运行符合模式的测试
uv run pytest -k "test_add_todo"

项目结构

things-mcp/
├── things_server.py     # 主MCP服务器实现
├── url_scheme.py        # Things URL方案实现
├── formatters.py        # 数据格式化工具
├── tests/               # 单元测试
│   ├── conftest.py      # 测试夹具和配置
│   ├── test_url_scheme.py
│   └── test_formatters.py
├── manifest.json        # DXT包清单
├── build_dxt.sh         # DXT包构建脚本
├── pyproject.toml       # 项目依赖项和pytest配置
└── run.sh               # 方便的运行脚本

故障排除

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

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