Omnifocus

OmniFocus MCP 服务

一个通过 Omni Automation 为 AI 助手提供完整 OmniFocus 访问能力的 MCP 服务。提供 41 个工具，涵盖任务、项目、文件夹、标签、子任务层级、通知、附件、分析和数据导出。

工作原理

该服务运行 osascript -l JavaScript 来调用 app.evaluateJavascript()，在 OmniFocus 原生 Omni Automation 引擎中执行脚本。不直接访问数据库——所有交互都通过官方 API 进行。

安装

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

MCP 客户端配置

将该服务添加到 MCP 客户端的配置中。服务条目如下：

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["/path/to/omnifocus-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

配置文件位置取决于客户端：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code：~/.claude/settings.json 或项目中的 .mcp.json
• 其他 MCP 客户端：请查阅客户端文档，了解服务配置方法

要求

• macOS（运行 osascript 所必需）
• 已安装 OmniFocus 4.6+
• Node.js 18+
• OmniFocus 的 macOS 自动化权限（首次使用时授予——请参阅 docs/PERMISSIONS.md）

工具

任务（7 个工具）

工具	描述
list_tasks	按完成状态、标记、项目、标签、日期、搜索、收件箱和可用状态筛选。缓存 30 秒。
get_task_count	统计符合条件的任务数量，不返回数据。
todays_agenda	获取今天到期、已逾期或已标记的任务。
create_task	创建任务，可设置名称、备注、标记、日期、标签、项目和预计用时。
update_task	修改任意任务属性。在项目之间移动任务。
complete_task	将任务标记为已完成。
delete_task	删除任务。

项目（5 个工具）

工具	描述
list_projects	按状态、标记和文件夹筛选。缓存 5 分钟。
create_project	创建项目并指定文件夹位置（如有需要会自动创建文件夹）。
update_project	修改属性，在文件夹之间移动项目。
complete_project	将项目标记为已完成（可选择同时完成所有任务）。
delete_project	删除项目。

文件夹（6 个工具）

工具	描述
list_folders	按嵌套深度和状态筛选并列出文件夹。
create_folder	创建文件夹，可选择嵌套。
update_folder	重命名、更改状态。
delete_folder	删除文件夹（可选择先移动其中的内容）。
get_folder_contents	列出文件夹中的项目和子文件夹。
move_to_folder	将项目或文件夹移入其他文件夹。

任务层级（5 个工具）

工具	描述
get_task_hierarchy	获取任务及其完整子任务树（可配置深度）。
create_subtask	创建子任务并控制其位置。
move_task	将任务移至其他父任务下，或移至项目根目录。
set_task_ordering	设置顺序/并行模式以及 completedByChildren。
list_subtasks	列出任务的直接子任务。

标签（2 个工具）

工具	描述
list_tags	列出所有标签。可选提供（开销较大的）使用统计信息。
manage_tags	创建、重命名、删除或合并标签。支持通过 parentTag 创建嵌套标签。

通知（4 个工具）

工具	描述
list_notifications	列出任务上的所有通知。
add_notification	添加绝对时间（日期）或相对时间（相对于到期时间的偏移量）通知。
remove_notification	按索引移除通知。
clear_notifications	移除任务的所有通知。

附件（4 个工具）

工具	描述
list_attachments	列出任务上的附件元数据和关联文件。
add_linked_file	将 file:// 路径关联到任务。
remove_attachment	按索引移除嵌入式附件。
remove_linked_file	取消关联文件引用。

分析（3 个工具）

工具	描述
get_productivity_stats	完成率、时间分布。按项目／标签／日／周分组。
get_task_velocity	按日／周／月统计任务吞吐量。
analyze_overdue_tasks	按项目／标签／逾期时长／优先级对逾期模式进行分组。

周期性任务（2 个工具）

工具	描述
analyze_recurring_tasks	列出周期性任务及其频率和到期日期。
get_recurring_patterns	周期性任务频率的统计数据。

导出（3 个工具）

工具	描述
export_tasks	将任务导出为 JSON 或 CSV，并选择字段。
export_projects	导出项目，可选择包含统计数据。
bulk_export	将所有数据（任务、项目、标签）导出到文件。

架构

src/
├── cache/           # TTL-based caching (30s tasks, 5min projects, 1h analytics)
├── omnifocus/
│   ├── OmniAutomation.ts   # Bridge: osascript → evaluateJavascript()
│   ├── scripts/             # Omni Automation script templates
│   └── types.ts             # Type definitions
├── tools/           # 41 MCP tools in 10 domain directories
│   ├── tasks/       ├── projects/    ├── folders/
│   ├── hierarchy/   ├── tags/        ├── notifications/
│   ├── attachments/ ├── analytics/   ├── recurring/
│   └── export/
├── utils/           # Logging, permission checking
└── index.ts         # Server entry point

脚本执行流程：

1. 工具调用 omniAutomation.buildScript(template, params) — 使用经过 JSON.stringify 转义的值替换 {{placeholders}}
2. wrapScript() 会将脚本包装在 try/catch IIFE 中
3. 再次使用 JSON.stringify 转义包装后的脚本，并将其传递给 app.evaluateJavascript()
4. osascript -l JavaScript 运行外层 JXA 包装器
5. 解析 JSON 结果，并通过 MCP 返回

已知限制

• 无法创建周期性任务 — 可以读取周期性模式，但无法创建重复规则
• 无法管理视角 — Omni Automation API 对视角仅提供只读权限
• 无法使用基于位置的标签 — 必须在 OmniFocus UI 中手动设置
• add_linked_file 只接受 file:// URL — OmniFocus 会拒绝 http/https
• MCP 服务会缓存构建结果 — Claude Code 必须重启才能加载 npm run build 的更改
• 无法通过自动化管理审阅／视角

开发

npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm test          # Unit tests (vitest)
npm run typecheck # Type check without building

许可证

MIT — 参见 LICENSE