Things3 MCP Server

Things3 MCP 服务

一个 MCP（Model Context Protocol）服务，提供与 macOS 上 Things3 的全面集成。该服务使 AI 助手和其他 MCP 客户端能够通过 25 个专用工具与 Things3 交互，提供完整的任务管理能力，并具备智能错误纠正和自动标签创建功能。

功能特性

• 完整的 Things3 集成：25 个工具，覆盖 Things3 的各个方面
• TODO 管理：创建、读取、更新、删除、完成和取消完成任务
• 项目与领域管理：支持完整的项目生命周期，包括领域组织和删除
• 标签系统：支持层级标签，可创建、删除和批量操作标签
• 批量操作：高效地一次性移动或更新多个项目
• 自动创建标签：在 TODO/项目操作中引用标签时会自动创建
• 错误纠正：自动修复常见问题（日期冲突、缺少标题）
• 日志簿搜索：按日期范围筛选搜索已完成的项目
• 性能优化：连接池和 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"
      }
    }
  }
}

从源码安装

# 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"

查找授权令牌的方法：

1. 打开 Things3
2. 进入设置 → 通用
3. 点击 "Enable Things URLs"
4. 点击 "Manage"
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 客户端格式调整配置。

可用工具

TODO 工具（7）

todos_list

列出 TODO，支持灵活的筛选选项。

参数：

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

示例：

{
  "filter": "today",
  "searchText": "meeting"
}

todos_get

获取特定 TODO 的详细信息。

参数：

• id：TODO 的唯一标识符（必填）

todos_create

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

参数：

• 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 时，待办事项会使用 Things3 的 URL scheme 创建，而不是 AppleScript。这种方式有一些限制：

• Things3 可能会短暂切换到前台
• 所创建待办事项的 ID 无法直接获取，因此服务会按标题搜索它
• 如果多个待办事项具有相同标题，可能会返回错误的待办事项
• 必须在 Things3 设置中启用 URL scheme 支持（Settings → General → Enable Things URLs）

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：项目标识符（必填）
• 除 headings 外，projects_create 中的所有参数（可选）

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

将多个 TODO 移动到项目或领域。

参数：

• todoIds：TODO ID 数组（必填）
• projectId：目标项目（可选）
• areaId：目标领域（可选）

bulk_updateDates

更新多个 TODO 的日期。

参数：

• todoIds：TODO ID 数组（必填）
• whenDate：新的计划日期，或 null 以清除（可选）
• deadline：新的截止日期，或 null 以清除（可选）

日志簿工具 (1)

logbook_search

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

参数：

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

系统工具 (1)

system_launch

确保 Things3 正在运行并已就绪。

错误纠正

服务会自动纠正常见问题：

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

使用示例

配合 Claude Desktop 使用

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

故障排除

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 不支持操作检查清单
   • 我们在创建带检查清单的 TODO 时使用 URL scheme 作为变通方案
   • 这可能会导致 Things3 短暂切换到前台
   • 已存在的检查清单事项在创建后无法修改
2. 已删除事项恢复：已删除的事项无法通过 API 恢复
3. 提醒详情：通过 AppleScript 可获取的提醒信息有限
4. 标签层级：标签的父子关系为只读（但可以创建和删除标签）
5. URL Scheme 限制：
   • 使用 URL scheme（用于检查清单）时，无法直接获取新建 TODO 的 ID
   • 服务会执行搜索以查找所创建的 TODO，如果多个 TODO 标题相同，可能会失败

贡献

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

致谢

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