Things MCP

things-mcp 允许你的编码代理（如 Claude、Cursor、Gemini、Copilot 等）通过其已记录的 URL 方案在 macOS 上驱动 Things 任务管理器。该服务器将每个 Things 命令封装为一个模型上下文协议（MCP）工具，因此你的助手可以创建、更新和显示待办事项和项目，而无需使用私有 API。

主要特性

• 一流的 Things 命令 – 提供 add、add-project、update、update-project、show、search、version 和 json 作为 MCP 工具。
• 安全的 URL 分发 – 规范化传出的 URL（例如，将空格替换为 %20），并支持可选的前台激活。
• 组合工具箱 – 每个工具返回调用的 Things URL，使得在代理中轻松记录或重试操作变得容易。

声明

things-mcp 通过其 URL 方案启动 Things。任何具有服务器访问权限的 MCP 客户端都可以浏览你的任务列表或创建/更新项目。仅启用受信任的助手和用户。

要求

• macOS 上安装了 Things 并且在 Things → 设置 → 通用中启用了“Things URLs”。
• Go 1.25.2（该仓库使用 Go 工具链管理器）。

快速开始

克隆仓库，然后构建和测试：

make test
make build   # 输出 bin/things-mcp

启动服务器。默认情况下 Things 会在后台运行；传递 ARGS="-activate" 来告诉二进制文件在每次命令后将 Things 带到前台：

make run                     # 使用后台 URL 启动
make run ARGS="-activate"    # 启动并使 Things 每次都处于前台

向你的客户端添加以下 MCP 服务器配置（根据需要调整二进制路径）：

{
  "mcpServers": {
    "things-mcp": {
      "command": "/Users/mgomes/Documents/Work/moonbase/things-mcp/bin/things-mcp",
      "args": []
    }
  }
}

当你希望 Things 处于前台时，在 args 数组中传递 "-activate" 或其他标志：

{
  "mcpServers": {
    事物-mcp": {
      "command": "/Users/mgomes/Documents/Work/moonbase/things-mcp/bin/things-mcp",
      "args": ["-activate"]
    }
  }
}

MCP 客户端配置

<details> <summary>Claude Desktop</summary> 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` 并在 `mcpServers` 下添加上述片段。之后重启 Claude Desktop。 </details> <details> <summary>Claude Code CLI</summary> 运行：

claude mcp add things-mcp /Users/mgomes/Documents/Work/moonbase/things-mcp/bin/things-mcp

如果你希望 Things 弹出到前台，请在二进制路径后面添加 -activate。

</details> <details> <summary>Cursor</summary> 转到 **设置 → MCP → 新 MCP 服务器**，选择“Stdio”，将命令设置为构建的二进制路径，并可选地在参数中添加 `-activate`。或者在 Cursor 中使用上述 JSON 的深度链接生成器。 </details> <details> <summary>Gemini CLI</summary>

gemini mcp add things-mcp /Users/mgomes/Documents/Work/moonbase/things-mcp/bin/things-mcp

如果你希望前台启动，请提供 --args -activate。

</details> <details> <summary>GitHub Copilot CLI</summary> 在 Copilot 提示符内运行 `/mcp add`，选择“本地”服务器类型，将命令设置为二进制路径，并留空参数（或根据需要添加 `-activate`）。 </details> <details> <summary>JetBrains AI Assistant / Junie</summary> 导航至 **设置 → 工具 → AI Assistant → 模型上下文协议**，点击 **添加**，将命令字段设置为构建的二进制文件，并指定任何参数。在 **设置 → 工具 → Junie → MCP 设置** 下重复相同的流程。 </details> <details> <summary>VS Code / Copilot Chat</summary> 运行：

code --add-mcp '{"name":"things-mcp","command":"/Users/mgomes/Documents/Work/moonbase/things-mcp/bin/things-mcp","args":[]}'

重新打开 VS Code 以便 Copilot Chat 加载服务器。

</details> <details> <summary>Warp</summary> 打开 **设置 → AI → 管理 MCP 服务器 → + 添加**，选择“本地”，并使用标准命令/参数片段。 </details>

工具

• things-add – 创建待办事项（支持多标题批次、标签、截止日期等）
• things-add-project – 创建项目，可选子待办事项和元数据
• things-update – 更新现有待办事项（需要 Things 认证令牌）
• things-update-project – 更新现有项目（需要认证令牌）
• things-show – 显示列表/项目/待办事项或快速查找查询
• things-search – 打开搜索界面，可选查询文本
• things-version – 显示 Things 构建/方案版本对话框
• things-json – 调用 JSON 批量命令进行复杂导入

每个工具返回带有分发 URL 的结构化输出，以便客户端可以显示或重用它。

测试

运行测试套件：

make test

测试涵盖 URL 编码、验证和 JSON 压缩逻辑。

已知限制

• Things URL 方案侧重于写入和导航；它不提供列出现有待办事项或项目的端点。当需要读取结构化数据时，请直接使用 Things（或其他集成）。