AI导哈

任务管理服务器

Things 3 MCP Server是一个高效的任务管理服务器，提供完整的CRUD操作，支持AppleScript和URL方案，适用于Claude Desktop和其他MCP兼容客户端。

  • by piersdd
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 piersdd/things-3-mcp

使用说明

Things 3 MCP服务器

一流的 主控程序 服务器 事情3 --令牌高效，完全CRUD，AppleScript+URL方案。

专为Claude Desktop、Claude Code和任何兼容MCP的客户端打造最强大、最高效的Things集成。

特性

  • 令牌高效输出 --默认情况下，每个项目简洁一行，按需详细说明
  • 30+工具 --全面覆盖每一个Things 3视图和操作
  • Smart Someday过滤 --正确处理继承的Someday状态（与Things UI完全匹配）
  • 随机抽样 — get_random_inbox(5) 用于可管理的LLM上下文，而不是转储数百个项目
  • 摘要模式 --完整的GTD概述(get_summary)约20行
  • AppleScript+URL方案 --具有UUID反馈的可靠写入；自动回退
  • 批量JSON导入/导出 --Things URL方案JSON格式
  • HTTP传输 -使用API密钥身份验证的可选远程访问
  • 技能.md --自学指导，以便克劳德最佳地使用工具

需求

  • macOS （Things 3仅适用于macOS/iOS）
  • 事情3 已安装并正在运行
  • Python 3.12+
  • 紫外线 （推荐）或pip

快速开始

安装并运行

# Clone and install
git clone https://github.com/piersdd/things-3-mcp.git
cd things-3-mcp
uv sync

# Run (stdio transport — for Claude Desktop)
uv run things3-mcp

Claude桌面配置

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "things3": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/things-3-mcp", "things3-mcp"]
    }
  }
}

克劳德代码

# Add as MCP server
claude mcp add things3 -- uv run --directory /path/to/things-3-mcp things3-mcp

代币保存提示

服务器旨在最大限度地减少LLM上下文消耗：

  1. 从...开始 get_summary() --20行GTD概述，而不是数百个任务
  2. 使用随机抽样 — get_random_inbox(5) 之前 get_inbox(limit=100)
  3. 默认值是有效的 — concise=True, limit=10 在所有工具上
  4. 单行格式: □ Buy groceries [3F8A2B1C] | today | deadline:2026-03-01 | #errands
  5. 省略空字段 --无“注释：无”或“标签：[]”杂乱
  6. 批量查找 --没有N+1个查询；批量解析项目/区域名称

所有工具（30）

列表视图（9）

工具 说明
get_inbox 未处理的任务
get_today 今天的日程安排（某一天过滤）
get_upcoming 未来计划的任务
get_anytime 可用任务
get_someday 延期任务（包括继承任务）
get_logbook 已完成的任务（可配置的时间段）
get_trash 废弃任务
get_deadlines 所有有截止日期的任务，已排序
get_summary 约20条线路的完整GTD概述

随机抽样（4）——推荐的切入点

工具 说明
get_random_inbox 收件箱中的随机样本
get_random_today 从今天开始随机抽样
get_random_anytime 随时随机采样
get_random_todos 随机样本，可选项目过滤器

实体视图（5）

工具 说明
get_todos 所有打开的待办事项（可选项目筛选器）
get_projects 有未完成/已完成计数的项目
get_areas 高级类别
get_tags 所有标签
get_tagged_items 带有特定标签的待办事项

搜索和详细信息（4）

工具 说明
search_todos 按标题/注释搜索
search_advanced 多过滤器搜索（状态、日期、标签、区域）
get_recent 最近创建的项目
show_item 按UUID列出单个项目，并提供完整详细信息

写入（4）--AppleScript主，URL方案回退

工具 说明
add_todo 创建todo（返回UUID）
add_project 创建一个带有可选待办事项的项目
update_todo 更新任何待办事项字段
update_project 更新任何项目字段

散装和导航（4）

工具 说明
json_import 通过Things JSON格式批量创建
json_export 将待办事项导出为紧凑的JSON
show_in_things 在Things应用程序中显示项目
search_in_things 打开物品搜索UI

HTTP传输

对于远程访问（例如，从不同的机器或移动设备）：

# Set environment variables
export THINGS_MCP_TRANSPORT=http
export THINGS_MCP_HOST=127.0.0.1
export THINGS_MCP_PORT=8765
export THINGS_MCP_API_KEY=your-secret-key-here  # auto-generated if empty

# Run
uv run things3-mcp

承载令牌身份验证

当通过隧道或反向代理暴露服务器时，设置 THINGS_MCP_API_TOKEN 在每次请求时都需要一个承载令牌：

export THINGS_MCP_API_TOKEN=your-secret-token-here

所有HTTP请求都必须包含标头：

Authorization: Bearer your-secret-token-here

接收没有有效令牌的请求 401 Unauthorized.如果env变量为 未设置或为空，bearer auth被禁用，服务器的行为与以前一样（仅适用于localhost访问）。

安全警告

切勿将HTTP端口直接暴露于互联网。 使用TLS反向代理：

  • Cloudflare 隧道 （建议使用免费、零配置TLS）
  • Caddy（自动HTTPS）
  • 带Let’s Encrypt的Nginx

Cloudflare隧道示例

# Install cloudflared
brew install cloudflare/cloudflare/cloudflared

# Create tunnel
cloudflared tunnel create things-mcp
cloudflared tunnel route dns things-mcp things-mcp.yourdomain.com

# Run tunnel
cloudflared tunnel --url http://localhost:8765 run things-mcp

测试HTTP端点

# Health check
curl http://localhost:8765/

# Call a tool (via MCP protocol)
curl -X POST http://localhost:8765/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key-here" \
  -d '{"method": "tools/call", "params": {"name": "get_summary", "arguments": {}}}'

环境变量

变量 默认值 描述
THINGS_MCP_TRANSPORT stdio stdio 或 http
THINGS_MCP_HOST 127.0.0.1 HTTP绑定地址
THINGS_MCP_PORT 8765 HTTP端口
THINGS_MCP_API_TOKEN （none） HTTP身份验证的承载令牌——如果已设置，则需要 Authorization: Bearer <token>
THINGS_MCP_API_KEY （自动） HTTP身份验证的API密钥（X-API-key头）
THINGS_AUTH_TOKEN （自动） Things URL方案认证令牌

建筑

src/things3_mcp/
├── server.py       # FastMCP instance + all 30 @mcp.tool definitions
├── formatters.py   # Two-tier output: concise (1-line) + detailed
├── someday.py      # Someday filtering (matches Things UI behavior)
├── applescript.py   # AppleScript bridge for writes (temp-file approach)
├── url_scheme.py   # URL scheme builder (fallback writes + checklist items)
├── sampling.py     # Random sampling helpers
├── auth.py         # API key auth for HTTP transport
└── models.py       # Shared constants

设计原则：

  • 阅读 通过 things.py （直接SQLite——快速，无需应用程序）
  • 写 通过AppleScript（可靠，返回UUID，不需要身份验证令牌）
  • 回退写 通过URL方案（用于检查表项目或AppleScript失败时）
  • 批量查找 在格式化程序中消除N+1个查询
  • 有一天过滤 处理Things 3项目继承边缘情况

发展

# Install with dev/test dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

许可证

麻省理工学院

相关 MCP