Things MCP

MCP服务器

这 模型上下文协议（MCP） 服务器允许您使用Claude Desktop与中的任务管理数据进行交互 事情3 来自文化代码。你可以让Claude创建任务、分析项目、帮助管理优先级等等。

支持项目

如果你觉得这个项目有帮助，可以考虑支持它的开发：

特性

• 访问所有主要事项列表（收件箱、今天、即将到来等）
• 项目和区域管理
• 标签操作
• 高级搜索功能
• 最近的项目
• 详细的项目信息，包括检查表
• 支持嵌套数据（区域内的项目，项目内的待办事项）
• Someday项目筛选：Someday项目中的任务会自动从Today、Upcoming和Anytime视图中排除，与Things UI行为相匹配

安装

先决条件

• macOS（Things 3仅适用于Mac）
• 启用“启用Things URL”的Things 3应用程序（设置→ 一般）
• MCP客户端，如Claude Desktop或Claude Code
• 紫外线 Python包管理器： brew install uv

通过uvx（任何MCP客户端）安装

Things MCP发布在PyPI上，可以直接运行 uvx:

uvx things-mcp

配置您的MCP客户端以使用 uvx 随着 things-mcp 作为论点。

克劳德桌面

选项1：一键安装（推荐）

1. 从下载最新文件 发布页面
2. 双击 .mcpb 文件
3. 完成！

选项2：手动配置

1. 首选 克劳德→ 设置→ 开发者→ 编辑配置
2. 添加Things服务器：

{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": ["things-mcp"]
    }
  }
}

1. 保存并重新启动Claude Desktop

克劳德代码

claude mcp add-json things '{"command":"uvx","args":["things-mcp"]}'

要使其在全球（所有项目）可用，请添加 -s user:

claude mcp add-json -s user things '{"command":"uvx","args":["things-mcp"]}'

验证它是否正常工作

安装后：

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

Claude Desktop使用示例

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

提示

• 使用自定义说明在Claude中创建一个项目，解释如何使用Things并组织区域、项目、标签等。告诉克劳德，当它创建新任务时，你希望包含哪些信息（例如，要求它在任务描述中包含相关细节可能会有所帮助）。
• 尝试添加另一个MCP服务器，让Claude访问您的日历。这将允许你让克劳德在日历上为特定任务留出时间，根据即将到来的日历事件创建待办事项（例如为会议做准备）等。
• 使用任务年龄来识别过时的项目：“我的Anytime列表中的哪些任务超过2周？”

可用工具

列表视图

• get-inbox -从收件箱获取待办事项
• get-today -获得今天到期的待办事项
• get-upcoming -获取即将到来的待办事项
• get-anytime -从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方案操作

• add-todo -创建新待办事项
• add-project -创建新项目
• update-todo -更新现有待办事项
• update-project -更新现有项目
• show-item -在Things中显示特定项目或列表
• search-items -在Things中搜索项目

工具参数

get-所有

• project_uuid （可选）-按项目筛选待办事项
• include_items （可选，默认值：true）-包括检查表项目

获取项目/获取区域/获取标签

• include_items （可选，默认值：false）-包括包含的项目

搜索高级

• status -按状态筛选（未完成/已完成/已取消）
• start_date -按开始日期（YYYY-MM-DD）筛选
• deadline -按截止日期筛选（YYYY-MM-DD）
• tag -按标签筛选
• area -按区域UUID筛选
• type -按项目类型（待办事项/项目/标题）筛选
• last -按创建日期筛选（例如，“3d”表示过去3天，“1w”表示上周）

获取最新信息

• period -时间段（例如，“3d”、“1w”、“2m”、“1年”）

使用提醒进行日程安排（添加待办事项、添加项目、更新待办事项、更新项目）

• when -接受多种格式：

- 关键词： today, tomorrow, evening, anytime, someday - 日期： YYYY-MM-DD （例如。， 2024-01-15) - 带提醒的日期时间： YYYY-MM-DD@HH:MM （例如。， 2024-01-15@14:30)

故障排除

如果它不起作用：

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

- Things数据库需要存在才能使服务器工作

1. 检查“启用事情URL”是否已打开

- 开放的事物→ 设置→ 将军→ 启用事物URL

1. Claude Desktop找不到 uvx

- 使用Homebrew在全球范围内安装uv(brew install uv) - 替代：使用完整路径 uvx 在您的配置中。找到它 which uvx （通常 /Users/USERNAME/.local/bin/uvx)

发展

运行测试

该项目包括一个用于URL方案和格式化器模块的全面单元测试套件。

# Install test dependencies
uv sync --extra test

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run a specific test file
uv run pytest tests/test_url_scheme.py

# Run tests matching a pattern
uv run pytest -k "test_add_todo"

MCP集成测试

该项目包括一个集成测试计划，可由Claude（通过Claude Cowork或Claude Code）执行，以验证所有MCP工具在实时数据库中是否正常工作。

看 docs/mcp_integration_test_plan.md 完整的测试计划。

项目结构

things-mcp/
├── src/things_mcp/      # Main package
│   ├── __init__.py      # Package exports
│   ├── __main__.py      # Entry point for python -m
│   ├── server.py        # MCP server implementation
│   ├── url_scheme.py    # Things URL scheme implementation
│   └── formatters.py    # Data formatting utilities
├── tests/               # Unit tests
│   ├── conftest.py      # Test fixtures and configuration
│   ├── test_url_scheme.py
│   ├── test_formatters.py
│   ├── test_someday_filtering.py
│   └── test_mcp_server_filtering.py
├── docs/                # Documentation
│   └── mcp_integration_test_plan.md  # Claude-executable integration test
├── manifest.json        # MCPB package manifest
├── build_mcpb.sh        # MCPB package build script
├── pyproject.toml       # Project dependencies, build config, and pytest config
├── .env.example         # Sample environment configuration
└── run.sh               # Convenience runner script

HTTP传输

默认情况下，服务器使用stdio传输与MCP客户端进行通信。对于远程访问场景，您可以使用HTTP传输运行服务器。

配置

设置这些环境变量以启用HTTP传输：

示例

# Using uvx
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uvx things-mcp

# Or from source
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uv run things-mcp

看 .env.example 查看示例配置文件。