Omnifocus MCP (Vitalyrodnenko)

OmniFocus MCP

   

MCP服务器，让AI助手完全控制 GTD 软件 在macOS上。

45个工具、3个资源和4个提示，涵盖任务、项目、标签、文件夹、透视图、预测、通知和审核工作流——所有这些都贯穿整个 模型上下文协议.

本项目不隶属于Omni Group或OmniFocus，也不受其认可或与之相关。OmniFocus是Omni Group的商标。这是一个独立的、非商业的开源项目。

快速开始

通过安装 家酿 （如果您没有Homebrew，请参阅 Homebrew安装指南):

brew tap vitalyrodnenko/omnifocus-mcp
brew install omnifocus-mcp

然后添加到您的MCP客户端配置（Claude Desktop、Cursor等）：

{
  "mcpServers": {
    "omnifocus": {
      "command": "omnifocus-mcp",
      "args": []
    }
  }
}

就是这样。人工智能助手现在可以完全访问OmniFocus。

它能做什么

任务（23个工具）

OmniFocus任务的完整生命周期管理：

• 增删改查 --创建、获取、更新、删除单个任务
• 批量操作 --在一次通话中创建、移动或删除多个任务
• 子任务 --在任何父任务下创建并列出子任务
• 完成 --标记已完成，标记未完成（支持重复任务）
• 搜索 --在应用了所有筛选器的情况下，对任务名称和注释进行全文搜索
• 移动和修复 --在项目之间重新定位任务，在其他任务下重新分配任务，或在不删除/重新创建的情况下将子任务移回收件箱/项目
• 重复 --克隆具有所有属性和可选子任务的任务
• 通知 --列出、添加和删除通知（绝对日期或相对偏移）
• 重复 --设定或明确带有时间表类型的重复规则（定期/完成后）
• 备注 --在不覆盖的情况下将文本附加到任务注释中
• 安全模型 --破坏性删除确认与非破坏性移动/更新工作流分开
• 总计数 --不列出单个任务的快速“多少”查询

高级过滤

list_tasks 和 search_tasks 支持强大的过滤器组合：

排序

所有列表/搜索工具支持 sortBy 和 sortOrder:

• 排序方式： name, dueDate, deferDate, completionDate, estimatedMinutes, project, flagged, addedDate, changedDate, plannedDate
• 别名： added -> addedDate, modified -> changedDate, planned -> plannedDate
• 排序顺序： asc （默认）或 desc
• 任务有效载荷包括 addedDate 和 changedDate （ISO 8601或 null)

项目（11个工具）

• 增删改查 --创建、获取、更新、删除项目
• 生命周期 --完成、未完成、设置状态（活动/暂停/已删除）
• 组织 --在文件夹之间移动，按名称搜索
• 过滤 --按文件夹、状态、完成日期范围、仅暂停标志
• 排序 --按姓名、截止日期或其他字段
• 总计数 --项目按状态计数，可选范围为文件夹

项目生命周期语义

• 使用 complete_project 当工作完成/关闭时。
• 使用 set_project_status 仅适用于组织状态：

- active =电流 - on_hold =暂停（UI措辞通常为“暂停”/“暂停”） - dropped =故意放弃/取消，未完成

• 使用 uncomplete_project 将已完成的项目重新打开为活动状态。
• 在面向用户的摘要中，

文件夹和状态转换），并且仅将不透明ID作为次要ID包含在内 参考文献

标签（5工具）

• 增删改查 --创建、更新（名称和状态）、删除
• 列表 --具有状态过滤器（活动/保留/删除/全部）、排序和限制
• 搜索 --模糊名称匹配

文件夹（5个工具）

• 增删改查 --创建、获取（包括子项目和子文件夹）、更新、删除
• 层级 --使用父参数创建嵌套文件夹
• 列表 --所有有限制的文件夹

预测（1个工具）

• 带部分的结构化视图：逾期、今天到期、标记、推迟和本周到期

视角（1个工具）

• 列出所有可用的OmniFocus视角

资源（3）

MCP客户端可用的实时快照：

提示（4）

即用型审核工作流：

实现

具有相同工具名称、参数和响应形状的三种实现：

详细的设置指南： 锈 · python · TypeScript

运作原理

服务器通过macOS运行JXA（JavaScript for Automation）脚本 osascript。每个脚本都使用OmniFocus evaluateJavascript 在OmniFocus内部执行Omni Automation JavaScript的桥梁，其中包含完整的API，如 flattenedTasks, Task.Status，以及 new Task() 可用。数据被序列化为JSON，并通过MCP协议返回，在所有三个实现中具有一致的模式。

MCP客户端配置示例

克劳德桌面版

{
  "mcpServers": {
    "omnifocus": {
      "command": "omnifocus-mcp",
      "args": []
    }
  }
}

光标

{
  "mcpServers": {
    "omnifocus": {
      "command": "omnifocus-mcp",
      "args": []
    }
  }
}

Python（源代码构建）

{
  "mcpServers": {
    "omnifocus": {
      "command": "uv",
      "args": ["run", "omnifocus-mcp"]
    }
  }
}

TypeScript（源代码构建）

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/OmnifocusMCP/typescript"
    }
  }
}

一次只启用一个OmniFocus MCP服务器，以避免重复的工具表面。

兼容性代码段：

{
  "mcpServers": {
    "omnifocus": {
      "command": "python",
      "args": ["-m", "omnifocus_mcp"]
    }
  }
}

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/OmnifocusMCP/typescript"
    }
  }
}

切换实现

在Rust、Python和TypeScript之间切换

• 当你想要一个预构建的时候使用Rust omnifocus-mcp 二元的。
• 在需要的时候使用Python uv 或 python -m 执行和快速本地迭代。
• 根据需要使用TypeScript node 执行从 typescript/dist/index.js.
• 重新启动MCP客户端，以便在切换实现后重新加载服务器命令。

先决条件

• macOS（必填——OmniFocus仅适用于macOS）
• OmniFocus已安装并正在运行
• 授予终端/编辑器的自动化权限（系统设置→ 隐私和安全→ 自动化）

仅适用于源代码构建：

• Python 3.11+和 uv （Python实现）
• Node.js 20+和npm（TypeScript实现）
• Rust工具链通过 rustup （Rust源代码构建）

贡献

欢迎通过具有明确范围和通过检查的集中拉取请求做出贡献。看 CONTRIBUTING.md 用于设置和验证步骤。

许可证

MIT。看 LICENSE 了解详情。