OmniFocus MCP 服务器

一个模型上下文协议（MCP）服务器，将 OmniFocus 连接到 Claude 和其他兼容 MCP 的 AI 助手。

概述

该服务器在 AI 助手和你的 OmniFocus 数据库之间架起桥梁。通过自然对话，助手可以查询、创建、编辑和删除任务与项目——包括批量操作。你可以用它做的一些事情：

• 将课程大纲 PDF 转换为一个完整指定的项目，包含任务、标签、推迟日期和截止日期

• 将会议记录转化为一系列行动

• 通过对话审计和重新组织你的标签、项目和文件夹

• 创建你的任务、项目和标签的可视化

• 在单个批量操作中处理数十个项目

Related MCP server: MCP OmniFocus

快速开始

前提条件

• 安装了 OmniFocus 的 macOS

• Node.js 20 或更高版本（用于 npx）

服务器首次与 OmniFocus 通信时，macOS 会要求你允许自动化访问。授予一次即可。

Claude Desktop

将服务器添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

然后重启 Claude Desktop。

Claude Code

claude mcp add omnifocus -- npx -y omnifocus-mcp

其他 MCP 客户端的工作方式相同：通过 stdio 启动 npx -y omnifocus-mcp。

示例对话

定向查询：

"显示我所有本周到期的已标记任务"

"我在 Work 文件夹中的下一步行动是什么？"

"统计每个项目中有多少任务"

重新组织：

"我希望每个任务都有一个能量级别标签。显示所有没有该标签的任务列表，以及你建议添加的标签。我会进行任何我认为合适的更改。然后在 OmniFocus 中进行更改。"

从任何地方捕获：

"好的，感谢你详细解释法治的重要性。在我的 activism 项目中添加一个重复任务，提醒我每周给代表打电话。在备注字段中包含本次对话的摘要。"

使用透视：

"我有哪些可用的透视？"

"显示我的 Inbox 透视中的内容"

处理记录或 PDF：

"我正在粘贴今天会议的记录。请分析它，并在 OmniFocus 中为分配给我的任何行动项创建任务。将它们放入我的 'Product Development' 项目中。"

工具

服务器提供 12 个工具。可选参数已标记。

query_omnifocus

使用定向过滤器查询任务、项目或文件夹——比转储整个数据库更快、更轻量。完整参考见 QUERY_TOOL_REFERENCE.md，实际示例见 QUERY_TOOL_EXAMPLES.md。

可用的过滤器：

• 容器：projectName（不区分大小写的部分匹配；"inbox" 针对收件箱）、projectId、folderId（包含子文件夹）、folderName（不区分大小写的部分匹配，包含子文件夹）

• 名称：taskName（不区分大小写的部分匹配）

• 标签：tags（精确匹配，区分大小写）

• 状态：status — 任务：Next、Available、Blocked、DueSoon、Overdue、Completed、Dropped；项目：Active、OnHold、Done、Dropped

• 日期，前瞻性：dueWithin、deferredUntil、plannedWithin（范围）、dueOn、deferOn、plannedOn（精确日期）。接受天数、"today"、"tomorrow"、"this week"、"next week" 或 ISO 日期

• 日期，回顾性：addedWithin、addedOn、completedWithin、completedOn、droppedWithin、droppedOn（已完成/已丢弃过滤器需要 includeCompleted: true）

• 标记与杂项：flagged、inbox、hasNote、isRepeating、reviewDue（仅项目）

dump_database

获取数据库的完整状态。用于全面分析；对于任何定向查询，优先使用 query_omnifocus。

• hideCompleted (可选)：隐藏已完成/已丢弃的任务（默认：true）

• hideRecurringDuplicates (可选)：隐藏重复任务的重复实例（默认：true）

add_omnifocus_task

创建新任务。

• name

• projectName (可选)：要添加任务的项目（默认为收件箱）

• parentTaskId / parentTaskName (可选)：嵌套在现有任务下

• note、dueDate、deferDate、plannedDate、flagged、estimatedMinutes、tags (全部可选)

• repeat (可选)：使其重复——参见 重复项目

add_project

创建新项目。

• name

• folderName (可选)：放置项目的文件夹

• sequential (可选)：任务是否必须按顺序完成

• note、dueDate、deferDate、flagged、estimatedMinutes、tags、repeat (全部可选)

edit_item

编辑现有任务或项目。也是移动项目的方式——设置 newProjectName 将任务移动到项目中，或设置为 ""/"inbox" 将其发送到收件箱。

• id 或 name：要编辑的项目（id 优先）

• itemType：task 或 project

• 通用：newName、newNote、newDueDate、newDeferDate、newFlagged、newEstimatedMinutes（日期为 ISO 格式；空字符串清除）

• 任务：newStatus（incomplete、completed、dropped、skipped — 仅适用于重复任务）、addTags、removeTags、replaceTags、newProjectName、newPlannedDate

• 项目：newProjectStatus（active、completed、dropped、onHold）、newFolderName、newSequential、markReviewed（根据项目的审查间隔设置下一个审查日期）

• 重复：newRepeat 设置新规则（与创建时的 repeat 形状相同）；newRepeat: null 清除它

remove_item

删除任务或项目。

• id 或 name：要删除的项目

• itemType：task 或 project

batch_add_items

在一次操作中创建多个任务和项目。每个项目接受与 add_omnifocus_task / add_project 相同的字段，外加 type（task 或 project）和可选的层次结构辅助：

• tempId：同一批次中其他项目可以引用的临时 ID

• parentTempId：将此项目嵌套在另一个批次项目的 tempId 下

{
  "items": [
    { "type": "project", "name": "My Project", "tempId": "proj1" },
    { "type": "task", "name": "First task", "parentTempId": "proj1" },
    { "type": "task", "name": "Parent task", "parentTempId": "proj1", "tempId": "t1" },
    { "type": "task", "name": "Subtask", "parentTempId": "t1" }
  ]
}

batch_remove_items

在一次操作中删除多个任务或项目。每个项目接受 id 或 name，外加 itemType。

list_perspectives

列出可用的透视，包括内置和自定义（自定义透视是 OmniFocus Pro 功能）。

• includeBuiltIn、includeCustom (可选，默认：true)

get_perspective_view

获取命名透视中可见的项目。

• perspectiveName：例如 Inbox、Flagged 或自定义透视名称

• limit (可选，默认：100)、includeMetadata (可选)、fields (可选)

list_tags

列出所有标签及其层次结构、活动状态和任务计数。

• includeDropped (可选，默认：false)

create_tag

创建标签，可选地嵌套在现有父标签下。

• name

• parentTagName / parentTagID (可选；ID 优先)

重复项目

add_omnifocus_task、add_project 和 batch_add_items 中的每个项目都接受 repeat 对象；edit_item 接受 newRepeat。你描述日程，服务器编译 ICS 重复规则，因此你永远不需要手写 RRULE。

{ "name": "Weekly review", "repeat": { "method": "start-after-completion", "unit": "week" } }
{ "name": "Strength work", "repeat": { "method": "fixed", "unit": "week", "weekdays": ["TU","TH"] } }

谨慎选择 method — 这是手动设置时最常出错的字段。使用 fixed，无论上一个是否完成，事件都会按计划出现，因此错过一周会留下积压。使用 start-after-completion，下一个事件从你实际完成时开始安排，因此习惯会简单地恢复。

使用 query_omnifocus 通过 repetitionRule（ICS 字符串）和 repetitionMethod 字段读回规则，或使用 isRepeating 过滤。

目前不支持：位置性月度规则（"第三个星期二"）、特定月份日期和结束条件（COUNT/UNTIL）。请在 OmniFocus 中直接设置这些。

资源

资源允许 MCP 客户端将 OmniFocus 数据作为上下文附加到对话中，无需工具调用。在 Claude Code 中，输入 @ 浏览它们；Claude Desktop 和其他支持资源的客户端可以直接附加它们。所有资源返回 JSON。

两个模板资源支持列出所有可用值并自动完成 {name} 参数。

服务器指令与日志

指令： 在 MCP 握手期间，服务器向客户端发送使用指南——工具选择建议（优先使用 query_omnifocus 而不是 dump_database）、过滤器提示和资源目录。无需配置。

日志： 服务器通过 MCP 日志协议发出结构化日志。客户端可以使用 logging/setLevel（debug、info、warning、error 等）调整详细程度。脚本执行时间和错误会自动记录。

工作原理

服务器通过 osascript 与 OmniFocus 通信，在适当的地方使用 JXA（JavaScript for Automation）和 OmniFocus 内嵌的 Omni Automation（OmniJS）。它基于官方的 MCP TypeScript SDK 构建，并通过 stdio 与客户端通信。

共享守护进程

启动 omnifocus-mcp 会启动一个小型 shim，它连接到一个共享的后台守护进程，如果该进程尚未运行则启动一个。机器上的每个客户端都有自己的独立 MCP 会话，但它们都运行在同一个进程中。

当多个代理同时使用 OmniFocus 时，这一点很重要。OmniFocus 是一个通过 AppleEvents 驱动的单线程应用程序，服务器限制了它并发运行的 osascript 调用数量。当每个客户端运行自己的服务器时，这个上限是按进程计算的——十个客户端意味着十个独立的预算同时指向一个应用，导致 AppleEvent 超时。共享一个进程使上限变为全局的。

守护进程监听一个位于 0700 权限目录（默认为 ~/.omnifocus-mcp/daemon-<version>.sock）中的 Unix 域套接字，因此访问由文件系统强制执行——没有网络端口，也没有令牌。当没有客户端连接超过空闲窗口时间后，它会自行退出，并将日志写入套接字旁边的 daemon.log。

套接字名称携带包版本号，这样升级后绝不会让你与旧版本的守护进程通信。升级后你可能会短暂看到两个守护进程：旧的那个继续为已连接的客户端服务，并在最后一个客户端断开后退出。仍连接到旧守护进程的客户端会通过带内方式收到通知——当有较新的守护进程在服务时，每个工具结果都会附带一行升级提示，因此没有人需要记得重新连接。

客户端配置没有任何变化。如果守护进程无法启动——例如不寻常的沙箱环境、只读的主目录——shim 会回退到在进程内运行独立服务器，与早期版本的行为完全一致。

环境变量

路线图

• MCP prompt 支持

• 操作项目和任务的通知

• 功能请求和已知问题请参阅 GitHub issues

贡献

欢迎贡献！请随时提交拉取请求。CI 会在每个 PR 上运行类型检查、单元测试和构建。

npm install
npm test            # unit tests
npm run build       # compile to dist/
npm run test:integration  # requires OmniFocus; creates and removes TEST:-prefixed items

许可证

MIT