omnifocus-mcp

一个面向 OmniFocus 的 MCP 服务器，将完整的 Omni Automation JavaScript API 暴露给 LLM 调用者。

仅限 macOS。 需要 OmniFocus 在同一台机器上运行。整个实现通过 osascript -l JavaScript 在 OmniFocus 内部运行 OmniJS 片段——不生成 AppleScript 字符串，也不受脚本字典（scripting dictionary）限制。

前提条件

• macOS（Omni Automation 仅支持 macOS；服务器在其他平台上无法启动）

• 已安装 OmniFocus 并正在运行

• Node.js ≥ 20

Related MCP server: OmniFocus MCP Server

安装

该包以 @scardis/omniFocus-mcp 的形式发布到 npm。

通过 npx 使用（无需安装）

添加到你的 MCP 客户端配置中（例如 Claude Desktop 的 claude_dextop_config.json）：

{
  "mcpServers": {
    "omnifocus": {
      "command": "npx",
      "args": ["-y", "@scardis/omnifocus-mcp"]
    }
  }
}

从源码安装

git clone https://github.com/steveardis/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

然后配置你的 MCP 客户端：

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["/absolute/path/to/omnifocus-mcp/dist/server.js"]
    }
  }
}

可用工具

读取

写入

寻址模型

此服务器返回的每个实体都包含一个稳定的 id 字段（来自 OmniFocus 的 id.primaryKey）。请在后续调用中使用此 ID，而不是名称。名称可能有歧义；ID 不会。

如果你只有名称而没有 ID，请使用 resolve_name。它会返回一个列表——如果返回多个候选，请检查 path 字段，并在继续任何写操作之前让用户进行消歧。

与其他 OmniFocus MCP 服务器对比

有两个值得注意的替代方案： themotionmachine/OmniFocus-MCP 和 jqlts1/omniFocus-mcp-enhanced（上述项目的分支，带有额外工具）。

脚本 API。 这些替代方案使用 JXA 脚本字典或 AppleScript 驱动 OmniFocus。此服务器只进行一次 JXA 调用——Application('OmniFocus').evaluateJavascript()——并在 OmniFocus 内部以 OmniJS（Omni Automation）运行所有逻辑。这样可以访问完整的 Omni Automation API 接口（重复规则、审查间隔、透视、预测、附件、URL 自动化等），而不是受限于功能较少的脚本字典。

参数注入。 这些替代方案通过字符串插值构建 osascript 命令，这可能因名称中的撇号、双引号、反斜杠和 Unicode 而失败。此服务器使用 JSON.stringify 将所有参数序列化为一个 JS 字值。

实体寻址。 这些替代方案主要按名称寻址实体。此服务器为每个实体返回稳定的 id（id.primaryKey），并提供 resolve_name 将名称映射到 ID 候选——返回所有匹配结果及完整路径，而不是在名称有歧义时静默选择其中一个。

完整 CRUD。 此服务器支持创建、编辑、完成、丢弃、删除和移动任务、项目、文件夹和标签——此外还支持重复规则和 OmniFocus 4 的计划日期。

开发

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build
npm run build

测试

单元测试（无需 OmniFocus）

npm test

集成测试

️ 集成测试将针对你的真实 OmniFocus 数据库运行。

每次测试运行都会创建一个名为 __MCP_TEST_<uuid>__ 的临时顶级文件夹，并在 teardown 时删除它。如果测试运行在 teardown 前被中断，请运行清理脚本：

npm run test:cleanup-fixtures

⚠️ 同步警告： 默认情况下，如果启用了 OmniFocus 同步，集成测试会拒绝运行，以防止测试数据传播到你的其他设备。请先禁用 OmniFocus 同步，或设置 MCP_TEST_ALLOW_SYNC=1 选择启用（测试数据将同步）：

# Default (refuses if sync enabled)
npm run test:integration

# With sync enabled (use carefully)
MCP_TEST_ALLOW_SYNC=1 npm run test:integration

清理残留的测试数据

npm run test:cleanup-fixtures

这会移除 OmniFocus 中因中断的测试运行而留下的任何 __MCP_TEST_*__ 文件夹以及孤立的 __mcp_*__ 项目/标签。

贡献

欢迎贡献！以下是入门方法：

1. Fork 并克隆 仓库

2. 安装依赖： npm install

3. 运行单元测试（无需 OmniFocus）：npm test

4. 运行集成测试（需要 macOS + OmniFocus）：npm run test:integration

提交 PR 之前

• npm run typecheck — 必须无错误通过

• npm test — 所有单元测试必须通过

• npm run test:integration — 所有集成测试必须通过（仅限 macOS）

• 保持改动聚焦——每个 PR 只包含一个功能或修复

架构概览

此服务器通过 osascript -l JavaScript 在 OmniFocus 内部运行 OmniJS 片段。每个工具分为三层：

• Schema（模式）（src/schemas/shapes.ts）——用于输入验证和输出解析的 Zod schemas

• Snippet（片段）（src/snippets/*. js）——在 OmniFocus 内部运行的 OmniJS 代码。纯 ES5 JavaScript（无导入、无 TypeScript）。参数通过 ARGS` 占位符注入。

• Tool handler（工具处理器）（src/tools/*. ts）——验证输入、调用 runSnippet()、解析结果

添加新工具时：

1. 在 src/schemas/shapes.ts 中定义输入/输出 schema，并从 src/schemas/index.ts 导出

2. 在 src/snippets/ 中创建 OmniJS 片段

3. 在 src/runtime/snippetLoader.ts 的 ALLOWED_SNIPPETS 中添加片段名称

4. 在 src/tools/ 中创建工具处理器，并在 src/tools/index.ts 中注册

5. 为 schema 添加单元测试，并添加针对 OmniFocus 运行的集成测试

编写 OmniJS 片段

片段在 OmniFocus 的 JavaScript 运行时中运行，而不是 Node.js。关键限制：

• ES5 风格 JavaScript — 使用 var、function(){}，在较旧版本的 OmniFocus 中不要使用箭头函数

• 无导入 — 所有 OmniJS 全局对象（flattenedTasks、flattenedProjects、moveTasks 等）都直接可用

• 返回 JSON — 始终使用 return JSON.stringify({ ok: true, data: ... })

• 错误模式 — 抛出命名错误（NotFoundError、ValidationError），bridge 会捕获并包装它们

许可证

MIT