Things3 MCP服务器
 ](https://badge.fury.io/js/things3-mcp)
MCP（模型上下文协议）服务器，提供与macOS上Things3的全面集成。该服务器使AI助手和其他MCP客户端能够通过25个专用工具与Things3交互，提供完整的任务管理功能，包括智能纠错和自动标签创建。
特性
- 完成Things3集成：25个工具，涵盖Things的各个方面3
- TODO管理：创建、读取、更新、删除、完成和不完成任务
- 项目和区域管理：提供完整的项目生命周期支持，包括区域组织和删除
- 标签系统：分层标记支持创建、删除和批量标记操作
- 批量操作：一次高效地移动或更新多个项目
- 自动标记创建：在TODO/项目操作中引用时，会自动创建标记
- 改错：自动修复常见问题（日期冲突、缺少标题）
- 日志搜索：使用日期范围筛选搜索已完成的项目
- 性能优化：连接池和AppleScript优化
需求
- macOS （Things3仅适用于macOS）
- Node.js >= 16.0.0
- 事物3 已安装应用程序
- AppleScript 在系统设置中启用访问
安装
快速入门（推荐）
您可以在不进行任何安装的情况下使用服务器：
{
"mcpServers": {
"things3": {
"command": "npx",
"args": ["things3-mcp@latest"],
"env": {
"THINGS3_AUTH_TOKEN": "your_auth_token_here"
}
}
}
}从npm安装
npm install -g things3-mcp然后添加到MCP客户端配置中：
{
"mcpServers": {
"things3": {
"command": "things3-mcp",
"env": {
"THINGS3_AUTH_TOKEN": "your_auth_token_here"
}
}
}
}从源代码安装
# Clone the repository
git clone https://github.com/urbanogardun/things3-mcp.git
cd things3-mcp
# Install dependencies
npm install
# Build the project
npm run build配置
环境变量
对于更新操作（修改、完成、删除），您需要设置Things3授权令牌：
export THINGS3_AUTH_TOKEN="your_auth_token_here"要查找您的授权令牌：
- 打开物品3
- 转到“设置”→ 将军
- 点击“启用事物URL”
- 点击“管理”
- 复制授权令牌值
您还可以创建 .env 文件（参见 .env.example).
适用于克劳德桌面
- 打开克劳德桌面配置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 使用以下方法之一添加Things3 MCP服务器：
方法1：使用npx（最简单，无需安装）
{
"mcpServers": {
"things3": {
"command": "npx",
"args": ["things3-mcp@latest"],
"env": {
"THINGS3_AUTH_TOKEN": "your_auth_token_here"
}
}
}
}方法2：全局npm安装
{
"mcpServers": {
"things3": {
"command": "things3-mcp",
"env": {
"THINGS3_AUTH_TOKEN": "your_auth_token_here"
}
}
}方法3：就地安装
{
"mcpServers": {
"things3": {
"command": "node",
"args": ["/absolute/path/to/things3-mcp/dist/index.js"]
}
}
}- 重新启动克劳德桌面
对于其他MCP客户端
使用上述任何方法，使配置适应MCP客户端的格式。
可用工具
TODO工具（7）
todos_list
列出具有灵活过滤选项的TODO。
参数：
filter:"inbox"|"today"|"upcoming"|"anytime"|"someday"|"logbook"（可选）searchText：在标题和注释中搜索（可选）
例子：
{
"filter": "today",
"searchText": "meeting"
}todos_get
获取特定TODO的详细信息。
参数：
id：TODO的唯一标识符（必需）
todos_create
创建一个具有完整属性支持的新TODO（如果标签不存在，则自动创建标签）。
参数：
title：任务标题（必填）notes：附加注释（可选）whenDate：用于日程安排的ISO 8601日期字符串（可选）deadline：ISO 8601到期日期字符串（可选）tags：标记名数组（可选）checklistItems：清单项目标题数组（可选）\*projectId：分配给项目（可选）areaId：分配到区域（可选）heading：要添加的项目标题（可选）
例子：
{
"title": "Review Q4 Report",
"notes": "Focus on revenue metrics",
"whenDate": "2024-12-15T09:00:00Z",
"deadline": "2024-12-20T17:00:00Z",
"tags": ["work", "urgent"],
"checklistItems": ["Review revenue", "Check expenses", "Update forecast"],
"projectId": "project-id-here"
}\* 检查表注释：何时 checklistItems TODO是使用Things3的URL方案而不是AppleScript创建的。这种方法有一些局限性：
- 事情3可能会短暂地成为焦点
- 无法直接检索创建的TODO ID，因此服务器按标题搜索它
- 如果多个TODO具有相同的标题，则可能会返回错误的TODO
- 必须在Things3设置中启用URL方案支持（设置→ 将军→ 启用事物URL）
todos_update
更新现有TODO的属性（如果标签不存在，则自动创建标签）。
参数：
id：TODO标识符（必需）- 所有参数来自
todos_create（可选）
todos_complete
将一个或多个TODO标记为已完成。
参数：
ids：单个ID或ID数组（必填）
todos_uncomplete
将一个或多个TODO标记为不完整。
参数：
ids：单个ID或ID数组（必填）
todos_delete
永久删除一个或多个TODO。
参数：
ids：单个ID或ID数组（必填）
项目工具（6）
projects_list
列出具有可选筛选的项目。
参数：
areaId：按区域筛选（可选）includeCompleted：包括已完成的项目（可选，默认值：false）
projects_get
获取详细的项目信息。
参数：
id：项目标识符（必填）
projects_create
创建新项目（如果标签不存在，则自动创建标签）。
参数：
name：项目名称（必填）notes：项目描述（可选）areaId：分配到区域（可选）whenDate：开始日期（可选）deadline：截止日期（可选）tags：标记名数组（可选）headings：章节标题数组（可选）
projects_update
更新项目属性（如果标记不存在，则自动创建标记）。
参数：
id：项目标识符（必填）- 所有参数来自
projects_create除了headings（可选）
projects_complete
将项目标记为已完成。
参数：
id：项目标识符（必填）
projects_delete
从Things3中完全删除项目。
参数：
ids：单个项目ID或项目ID数组（必填）
区域工具（3）
areas_list
列出所有区域。
参数：
includeHidden：包括隐藏区域（可选，默认值：false）
areas_create
创建一个新区域。
参数：
name：区域名称（必填）
areas_delete
从Things3中完全删除区域。
参数：
ids：单个区域ID或区域ID数组（必填）
标签工具（5）
tags_list
列出所有具有层次结构信息的标签。
退货： 标签数组 parentTagId 用于嵌套标签
tags_create
创建一个新标签。
参数：
name：标签名称（必填）parentTagId：嵌套的父标记（可选）
tags_add
为项目添加标签（如果标签不存在，则自动创建标签）。
参数：
itemIds：单个ID或TODO/项目ID数组（必需）tags：要添加的标记名数组（必需）
tags_remove
从项目中删除标签。
参数：
itemIds：单个ID或TODO/项目ID数组（必需）tags：要删除的标记名数组（必需）
tags_delete
从Things3中完全删除标签。
参数：
names：单个标记名或标记名数组（必填）
散装工具（2）
bulk_move
将多个TODO移动到一个项目或区域。
参数：
todoIds：TODO ID数组（必需）projectId：目标项目（可选）areaId：目标区域（可选）
bulk_updateDates
多个TODO的更新日期。
参数：
todoIds：TODO ID数组（必需）whenDate：新的计划日期或清除空值（可选）deadline：新的截止日期或清空（可选）
行车日志工具（1）
logbook_search
在日志中搜索已完成的项目。
参数：
searchText：在标题和注释中搜索（可选）fromDate：范围的开始日期（可选）toDate：范围的结束日期（可选）limit：最大结果（可选，默认值：50）
系统工具（1）
system_launch
确保Things3正在运行并准备就绪。
改错
服务器会自动纠正常见问题：
- 日期冲突：如果截止日期早于计划日期，则交换时间/截止日期
- 缺少标题：从笔记生成标题或使用“无标题”
- 引用无效：如果项目/区域不存在，则将项目移动到收件箱
- 标记名称：清除Things3不支持的特殊字符
使用示例
使用克劳德桌面
Human: Create a new project for the website redesign with tasks for planning, design, and implementation
Claude: I'll create a website redesign project with those tasks for you.
[Creates project and tasks using the Things3 MCP tools]直接工具使用
创建TODO：
{
"tool": "todos_create",
"parameters": {
"title": "Prepare presentation",
"notes": "Include Q4 metrics and projections",
"whenDate": "2024-12-10T14:00:00Z",
"tags": ["work", "presentation"]
}
}列出今天的任务：
{
"tool": "todos_list",
"parameters": {
"filter": "today"
}
}发展
设置开发环境
# Install dependencies
npm install
# Run in development mode with watch
npm run dev
# Run tests
npm test
# Run integration tests (requires Things3)
npm run test:integration
# Lint code
npm run lint
# Type check
npm run type-check项目结构
things3-mcp/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server implementation
│ ├── config.ts # Configuration management
│ ├── tools/ # Tool implementations
│ │ ├── todos.ts # TODO operations
│ │ ├── projects.ts # Project operations
│ │ ├── areas.ts # Area operations
│ │ ├── tags.ts # Tag operations
│ │ ├── bulk.ts # Bulk operations
│ │ ├── logbook.ts # Logbook search
│ │ └── system.ts # System utilities
│ ├── templates/ # AppleScript templates
│ ├── utils/ # Utility functions
│ │ ├── applescript.ts # AppleScript bridge
│ │ ├── cache-manager.ts # Caching system
│ │ ├── error-correction.ts # Error correction
│ │ └── date-handler.ts # Date formatting
│ └── types/ # TypeScript definitions
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
└── dist/ # Compiled JavaScript故障排除
Things 3未响应
- 确保Things3已安装并正在运行
- 在系统设置>隐私和安全>隐私>自动化中检查AppleScript权限
- 授予您的终端或IDE控制Things3的权限
权限错误
- macOS可能要求您授予自动化权限
- 运行此命令以测试AppleScript访问：
osascript -e 'tell application "Things3" to return name of first to do'MCP连接问题
- 验证配置中的路径是否为绝对路径
- 检查服务器是否成功构建：
npm run build - 在MCP客户端的日志中查找错误消息
- 尝试直接运行服务器：
node dist/index.js
日期格式问题
- 日期必须采用ISO 8601格式（例如，“2024-12-25T10:00:00Z”）
- 服务器自动处理时区转换
- 如果日期显示不正确，请检查系统的日期格式设置
性能问题
- 对于大型操作，使用批量工具而不是单个操作
- 标签操作会自动创建缺失的标签，这可能会减缓初始操作的速度
已知限制
- 检查表项目:
- Things3的AppleScript API不支持检查表操作 - 在创建带有清单的TODO时，我们使用URL方案作为解决方法 - 这可能会导致Things3短暂地出现在前台 - 创建后无法修改现有检查表项
- 已删除邮件恢复：已删除的项目无法通过API恢复
- 提醒详细信息：通过AppleScript提供的提醒信息有限
- 标签层次结构：标记父子关系是只读的（但可以创建和删除标记）
- URL方案限制:
- 使用URL方案（用于检查表）时，无法直接检索新创建的TODO ID - 服务器执行搜索以查找创建的TODO，如果多个TODO具有相同的标题，则可能会失败
贡献
欢迎投稿！请遵循传统的提交格式，并确保在提交拉取请求之前通过所有测试。
致谢
- 与 模型上下文协议SDK
- 与集成 事物3 通过文化代码
- 受到MCP社区和各种自动化工具的启发
