事物3-mcp

Name: 事物3-mcp
Author: urbanogardun

作者：urbanogardun13 星标更新：2025-06-12

安装使用来源：spider==github.com

项目介绍

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"

要找到您的授权令牌：

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

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

对于 Claude Desktop

打开 Claude Desktop 配置：
- 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"]
    }
  }
}

重启 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 无响应

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

贡献

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

致谢

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