Things3 MCP Server

一个提供与 macOS 上 Things3 完整集成的 MCP（模型上下文协议）服务器。此服务器使 AI 助手和其他 MCP 客户端能够通过 25 个专用工具与 Things3 进行交互，提供全面的任务管理功能，包括智能错误纠正和自动标签创建。

功能

• 完整的 Things3 集成：涵盖 Things3 所有方面的 25 个工具
• 待办事项管理：创建、读取、更新、删除、完成和取消完成任务
• 项目及区域管理：支持项目的整个生命周期，包括区域组织和删除
• 标签系统：支持分层标签，包括创建、删除和批量标签操作
• 批量操作：高效地移动或更新多个项目
• 自动标签创建：在待办事项/项目操作中引用时自动创建标签
• 错误纠正：自动修复常见问题（日期冲突、缺少标题）
• 日志搜索：按日期范围过滤搜索已完成的项目
• 性能优化：连接池和 AppleScript 优化

要求

• macOS（Things3 仅适用于 macOS）
• Node.js >= 16.0.0
• 已安装 Things3 应用
• 在系统设置中启用 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"
      }
    }
  }
}

从源码安装

# 克隆仓库
git clone https://github.com/urbanogardun/things3-mcp.git
cd things3-mcp

# 安装依赖
npm install

# 构建项目
npm run build

配置

环境变量

对于更新操作（修改、完成、删除），您需要设置您的 Things3 授权令牌：

export THINGS3_AUTH_TOKEN="your_auth_token_here"

要找到您的授权令牌：

1. 打开 Things3
2. 前往 设置 → 通用
3. 点击“启用 Things URL”
4. 点击“管理”
5. 复制授权令牌值

您也可以创建一个 .env 文件（参见 .env.example）。

对于 Claude Desktop

1. 打开 Claude Desktop 配置：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

2. 使用以下方法之一添加 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"]
       }
     }
   }
   

3. 重启 Claude Desktop

对于其他 MCP 客户端

使用上述任一方法，根据您的 MCP 客户端格式调整配置。

可用工具

待办事项工具（7）

todos_list

列出待办事项，具有灵活的筛选选项。

参数：

• filter: "inbox" | "today" | "upcoming" | "anytime" | "someday" | "logbook"（可选）
• searchText: 在标题和备注中搜索（可选）

示例：

{
  "filter": "today",
  "searchText": "会议"
}

todos_get

获取特定待办事项的详细信息。

参数：

• id: 待办事项的唯一标识符（必需）

todos_create

创建一个新的待办事项，支持所有属性（如果不存在则自动创建标签）。

参数：

• title: 任务标题（必需）
• notes: 额外备注（可选）
• whenDate: ISO 8601 格式的调度日期字符串（可选）
• deadline: ISO 8601 格式的截止日期字符串（可选）
• tags: 标签名称数组（可选）
• checklistItems: 检查项标题数组（可选）*
• projectId: 分配给项目（可选）
• areaId: 分配给区域（可选）
• heading: 项目内的标题，用于添加到其中（可选）

示例：

{
  "title": "审查 Q4 报告",
  "notes": "关注收入指标",
  "whenDate": "2024-12-15T09:00:00Z",
  "deadline": "2024-12-20T17:00:00Z",
  "tags": ["工作", "紧急"],
  "checklistItems": ["审查收入", "检查支出", "更新预测"],
  "projectId": "project-id-here"
}

* 关于检查项：当提供 checklistItems 时，待办事项是使用 Things3 的 URL 方案而不是 AppleScript 创建的。这种方法有一些限制：

• Things3 可能会短暂地出现在前台
• 创建的待办事项的 ID 无法直接检索，因此服务器通过标题进行搜索
• 如果多个待办事项具有相同的标题，则可能会返回错误的待办事项
• 必须在 Things3 设置中启用 URL 方案支持（设置 → 通用 → 启用 Things URL）

todos_update

更新现有待办事项的属性（如果不存在则自动创建标签）。

参数：

• id: 待办事项标识符（必需）
• todos_create 中的所有参数（可选）

todos_complete

标记一个或多个待办事项为已完成。

参数：

• ids: 单个 ID 或 ID 数组（必需）

todos_uncomplete

标记一个或多个待办事项为未完成。

参数：

• ids: 单个 ID 或 ID 数组（必需）

todos_delete

永久删除一个或多个待办事项。

参数：

• 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 或待办事项/项目 ID 数组（必需）
• tags: 要添加的标签名称数组（必需）

tags_remove

从项目中移除标签。

参数：

• itemIds: 单个 ID 或待办事项/项目 ID 数组（必需）
• tags: 要移除的标签名称数组（必需）

tags_delete

从 Things3 中完全删除标签。

参数：

• names: 单个标签名称或标签名称数组（必需）

批量工具（2）

bulk_move

将多个待办事项移动到项目或区域。

参数：

• todoIds: 待办事项 ID 数组（必需）
• projectId: 目标项目（可选）
• areaId: 目标区域（可选）

bulk_updateDates

更新多个待办事项的日期。

参数：

• todoIds: 待办事项 ID 数组（必需）
• whenDate: 新的调度日期或 null 清除（可选）
• deadline: 新的截止日期或 null 清除（可选）

日志工具（1）

logbook_search

在日志中搜索已完成的项目。

参数：

• searchText: 在标题和备注中搜索（可选）
• fromDate: 范围的起始日期（可选）
• toDate: 范围的结束日期（可选）
• limit: 最大结果数（可选，默认值：50）

系统工具（1）

system_launch

确保 Things3 正在运行并准备好。

错误纠正

服务器自动纠正常见的问题：

• 日期冲突：如果截止日期早于计划日期，则交换两者
• 缺少标题：从备注生成标题或使用“无标题”
• 无效引用：如果项目/区域不存在，则将项目移动到收件箱
• 标签名称：清除 Things3 不支持的特殊字符

使用示例

与 Claude Desktop 结合使用

人类：为网站重新设计创建一个新项目，其中包括规划、设计和实施的任务

Claude：我将为您创建一个包含这些任务的网站重新设计项目。

[使用 Things3 MCP 工具创建项目和任务]

直接工具使用

创建一个待办事项：

{
  "tool": "todos_create",
  "parameters": {
    "title": "准备演示",
    "notes": "包括 Q4 指标和预测",
    "whenDate": "2024-12-10T14:00:00Z",
    "tags": ["工作", "演示"]
  }
}

列出今天的任务：

{
  "tool": "todos_list",
  "parameters": {
    "filter": "today"
  }
}

开发

设置开发环境

# 安装依赖
npm install

# 以监视模式运行开发
npm run dev

# 运行测试
npm test

# 运行集成测试（需要 Things3）
npm run test:integration

# 代码检查
npm run lint

# 类型检查
npm run type-check

项目结构

things3-mcp/
├── src/
│   ├── index.ts          # 入口点
│   ├── server.ts         # MCP 服务器实现
│   ├── config.ts         # 配置管理
│   ├── tools/            # 工具实现
│   │   ├── todos.ts      # 待办事项操作
│   │   ├── projects.ts   # 项目操作
│   │   ├── areas.ts      # 区域操作
│   │   ├── tags.ts       # 标签操作
│   │   ├── bulk.ts       # 批量操作
│   │   ├── logbook.ts    # 日志搜索
│   │   └── system.ts     # 系统实用工具
│   ├── templates/        # AppleScript 模板
│   ├── utils/            # 实用函数
│   │   ├── applescript.ts     # AppleScript 桥接
│   │   ├── cache-manager.ts   # 缓存系统
│   │   ├── error-correction.ts # 错误纠正
│   │   └── date-handler.ts    # 日期格式化
│   └── types/            # TypeScript 定义
├── tests/
│   ├── unit/            # 单元测试
│   └── integration/     # 集成测试
└── dist/                # 编译后的 JavaScript

故障排除

Things3 无响应

1. 确保已安装并运行 Things3
2. 检查系统设置中的 AppleScript 权限（隐私与安全 → 隐私 → 自动化）
3. 授予您的终端或 IDE 控制 Things3 的权限

权限错误

• macOS 可能需要授予自动化权限
• 运行以下命令以测试 AppleScript 访问权限：

  osascript -e 'tell application "Things3" to return name of first to do'
  

MCP 连接问题

1. 验证配置中的路径是否绝对
2. 检查服务器是否成功构建：npm run build
3. 查看 MCP 客户端的日志中的错误消息
4. 尝试直接运行服务器：node dist/index.js

日期格式问题

• 日期必须为 ISO 8601 格式（例如，“2024-12-25T10:00:00Z”）
• 服务器会自动处理时区转换
• 如果日期显示不正确，请检查系统中的日期格式设置

性能问题

• 对于大型操作，请使用批量工具而不是单独的操作
• 标签操作会自动创建缺失的标签，这可能在初始操作时减慢速度

已知限制

1. 检查项：
   • Things3 的 AppleScript API 不支持检查项操作
   • 当创建带有检查项的待办事项时，我们使用 URL 方案作为解决方法
   • 这可能会导致 Things3 短暂地出现在前台
   • 创建后无法修改现有的检查项
2. 删除项目恢复：无法通过 API 恢复已删除的项目
3. 提醒详情：通过 AppleScript 可用的提醒信息有限
4. 标签层级：标签的父子关系只读（但可以创建和删除标签）
5. URL 方案限制：
   • 使用 URL 方案（用于检查项）时，新创建的待办事项的 ID 无法直接检索
   • 服务器通过搜索来查找创建的待办事项，如果多个待办事项具有相同的标题，则可能会失败

贡献

欢迎贡献！请遵循常规提交格式，并确保所有测试通过后再提交拉取请求。

致谢

• 使用 Model Context Protocol SDK 构建
• 与 Cultured Code 的 Things3 集成
• 受 MCP 社区和各种自动化工具的启发