omnifocus-mcp
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
安装
该包以 @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"]
}
}
}可用工具
读取
工具 | 描述 |
| 项目,可按 status、folderId、flagged 过滤。默认排除已完成/已丢弃。限制(默认 100)。 |
| 通过稳定 ID 获取完整的项目详情 |
| 任务,按 |
| 通过稳定 ID 获取完整任务详情——包括 defer/planned/due 日期、标签、重复规则、parentTaskId |
| 文件夹,可按状态过滤。限制(默认 200)。 |
| 通过稳定 ID 获取完整文件夹详情,包括子文件夹和项目 ID |
| 标签,可按状态过滤。限制(默认 200)。 |
| 通过稳定 ID 获取完整标签详情,包括子标签 ID |
| 将名称解析为稳定 ID 候选——绝不静默消歧;返回所有匹配结果 |
写入
工具 | 描述 |
| 在收件箱、项目中创建任务,或创建为子任务。支持 defer/planned/due 日期、标签、flagged、预计分钟数和重复规则。 |
| 编辑任意任务字段。传入 |
| 将任务标记为已完成 |
| 将任务标记为已丢弃 |
| 永久删除任务及所有子任务 |
| 创建项目,可选择在文件夹中创建。支持类型、状态、审查间隔、标签。 |
| 编辑项目字段 |
| 将项目标记为已完成 |
| 将项目标记为已丢弃 |
| 永久删除项目及其所有任务 |
| 创建文件夹,可选择嵌套创建 |
| 重命名文件夹 |
| 永久删除文件夹及其整个子树 |
| 创建标签,可选择嵌套创建 |
| 编辑标签名称或状态 |
| 永久删除标签及子标签 |
| 将任务移动到项目,或作为另一个任务的子任务 |
| 将项目移动到文件夹或顶层 |
寻址模型
此服务器返回的每个实体都包含一个稳定的 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_*__ 项目/标签。
贡献
欢迎贡献!以下是入门方法:
Fork 并克隆 仓库
安装依赖:
npm install运行单元测试(无需 OmniFocus):
npm test运行集成测试(需要 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 schemasSnippet(片段)(
src/snippets/*. js)——在 OmniFocus 内部运行的 OmniJS 代码。纯 ES5 JavaScript(无导入、无 TypeScript)。参数通过ARGS` 占位符注入。Tool handler(工具处理器)(
src/tools/*. ts)——验证输入、调用runSnippet()、解析结果
添加新工具时:
在
src/schemas/shapes.ts中定义输入/输出 schema,并从src/schemas/index.ts导出在
src/snippets/中创建 OmniJS 片段在
src/runtime/snippetLoader.ts的ALLOWED_SNIPPETS中添加片段名称在
src/tools/中创建工具处理器,并在src/tools/index.ts中注册为 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 会捕获并包装它们
许可证
Available Tools
27 toolscomplete_projectB
Mark a project as done (complete). Returns the updated project detail.
Inputs: id (required).
complete_taskB
Mark a task complete by its stable ID. Returns the updated task detail.
Inputs: id (required).
create_folderA
Create a new OmniFocus folder. Omit parentFolderId to create at the top level; provide parentFolderId to nest it inside an existing folder.
Inputs: name (required), parentFolderId.
create_projectA
Create a new OmniFocus project. Omit folderId to create at the top level; provide folderId to place it inside a folder. Optionally set type (parallel/sequential/singleActions), status (active/onHold), review interval, and tags.
Inputs: name (required), note, type, status, +6 more.
create_tagA
Create a new OmniFocus tag. Omit parentTagId to create at the top level; provide parentTagId to nest it under an existing tag.
Inputs: name (required), parentTagId.
create_taskA
Create a new task. Placement: omit projectId and parentTaskId for inbox; provide projectId to add to a project; provide parentTaskId to create a subtask. Providing both projectId and parentTaskId is an error.
Inputs: name (required), note, tagIds, dueDate, +7 more.
delete_folderA
Permanently and recursively delete an OmniFocus folder. THIS ACTION CANNOT BE UNDONE. The ENTIRE subtree is destroyed: all child folders, all projects within those folders, and all tasks within those projects. Before calling this tool you MUST ask the user to explicitly confirm they want to permanently delete the folder and all of its contents.
Inputs: id (required).
delete_projectA
Permanently delete a project and ALL its tasks. THIS ACTION CANNOT BE UNDONE. Before calling this tool you MUST ask the user to explicitly confirm they want to permanently delete the project, and inform them that all tasks within the project will also be deleted.
Inputs: id (required).
delete_tagA
Permanently delete an OmniFocus tag. THIS ACTION CANNOT BE UNDONE. All child tags are also deleted, and all tasks/projects that held this tag have it removed automatically. Before calling this tool you MUST ask the user to explicitly confirm they want to permanently delete the tag and all its child tags.
Inputs: id (required).
delete_taskA
Permanently delete a task and all its subtasks. THIS ACTION CANNOT BE UNDONE. Before calling this tool you MUST ask the user to explicitly confirm they want to permanently delete the task, and inform them that all subtasks will also be deleted.
Inputs: id (required).
drop_projectA
Mark a project as dropped. Returns the updated project detail.
Inputs: id (required).
drop_taskA
Mark a task dropped by its stable ID. Returns the updated task detail.
Inputs: id (required).
edit_folderB
Rename an existing OmniFocus folder by its ID.
Inputs: id (required), name (required).
edit_projectA
Edit an existing project. Only provided fields are changed. Pass null for deferDate, dueDate, or reviewInterval to clear them. When tagIds is provided it replaces the full tag set.
Inputs: id (required), name, note, type, +6 more.
edit_tagA
Edit an existing OmniFocus tag. Provide id plus any combination of name (rename) and status (active/onHold/dropped).
Inputs: id (required), name, status.
edit_taskA
Edit an existing task by its stable ID. Only fields included in the call are changed; omitted fields are left unchanged. When tagIds is provided it replaces the full tag set. To clear a date field, pass clearDeferDate, clearPlannedDate, or clearDueDate set to true. Pass null for estimatedMinutes to clear it. To set a repetition rule, pass repetitionRule with frequency/interval/method. To clear repetition, pass clearRepetitionRule: true.
Inputs: id (required), name, note, tagIds, +10 more.
get_folderA
Get full detail for a folder by its stable ID. Returns path, parentId, status, child folder IDs, and immediate project IDs.
Inputs: id (required).
get_projectA
Get full detail for a project by its stable ID. Returns note, folder path, status, type, dates, review metadata, and tag IDs.
Inputs: id (required).
get_tagA
Get full detail for a tag by its stable ID. Returns path, parentId, status, and child tag IDs.
Inputs: id (required).
get_taskA
Get full detail for a task by its stable ID. Returns note, status, flagged, defer/due/completion dates, estimated minutes, container info, tag IDs, and parentTaskId (null for top-level tasks, set to the parent task's ID for subtasks).
Inputs: id (required).
list_foldersA
List folders in OmniFocus. By default, all folders (active and dropped) are returned. Optional filter.status ('active' | 'dropped') restricts to that status. Results are capped at limit (default 200). Each folder includes id, name, full path (ancestors joined with ▸), parentId, and status.
Inputs: limit, filter.
list_projectsA
List projects in OmniFocus. By default, done and dropped projects are excluded — pass filter.status to override. Optional filter fields: status (array of status strings), folderId (restricts to that folder's subtree), flagged (boolean). Results are capped at limit (default 100). Each project includes folderId and flagged in addition to id, name, folderPath, status, and type.
Inputs: limit, filter.
list_tagsA
List tags in OmniFocus. By default, all tags (active, onHold, and dropped) are returned. Optional filter.status ('active' | 'onHold' | 'dropped') restricts to that status. Results are capped at limit (default 200). Each tag includes id, name, full path (ancestors joined with ▸), parentId, and status.
Inputs: limit, filter.
list_tasksA
List tasks in OmniFocus within a scope. Provide exactly one of: projectId (tasks in a project), folderId (tasks across all projects in a folder), inbox (inbox tasks), or all (every task). By default, complete and dropped tasks are excluded — pass filter.status to override. Optional filter fields: flagged (boolean), status (array of status strings), tagId (string), dueBeforeDate (ISO datetime). Results are capped at limit (default 200). Each returned task includes dueDate and tagIds.
Inputs: scope (required), limit, filter.
move_projectA
Move a project to a different folder or to the top level. Pass folderId as a string to move into a folder, or null to move to the top level. Throws a not-found error if either ID does not exist.
Inputs: id (required), folderId (required).
move_taskA
Move a task to a different project (making it a top-level task) or make it a subtask of another task. Exactly one of projectId or parentTaskId must be provided. Throws a not-found error if any ID does not exist.
Inputs: id (required), projectId, parentTaskId.
resolve_nameA
Resolve an entity name to its stable ID(s). Returns ALL matches — never silently picks one. If multiple candidates are returned, ask the user or caller to disambiguate using the path field before proceeding with a write operation.
Inputs: type (required), query (required), scope.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Each tool targets a distinct resource/action combination: folders, tags, projects, and tasks each have their own CRUD and lifecycle tools. Overlapping verbs like complete, drop, and delete are clearly differentiated by their status-only versus destructive semantics.
Tool names consistently follow a verb_noun snake_case pattern: list_projects, get_task, create_folder, edit_tag, delete_project, complete_task, drop_project, and move_task. The naming style is uniform across all resources, making the set predictable and easy to navigate.
27 tools exceeds the 25+ threshold and feels heavy even though the server covers four distinct OmniFocus entity types. Each tool has a clear purpose, but the overall surface is larger than a typical well-scoped MCP server needs.
The tool set provides strong lifecycle coverage for folders, tags, projects, and tasks, including list/get/create/edit/delete plus task/project state transitions and moves. Minor gaps exist, such as no direct way to move folders or tags after creation and no explicit reopen/restore operation, but most workflows are well supported.
Maintenance
Related MCP Connectors
Create, schedule, and run JavaScript jobs, manage files, and inspect runs from your AI agent.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Official Akiflow MCP for tasks, calendars, scheduling, time slots, and meeting transcripts.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI-powered task management in OmniFocus with support for project reviews, planned dates, repeating tasks, custom perspectives, hierarchical subtasks, and advanced filtering. Perfect for Claude AI integration with comprehensive CRUD operations for tasks, projects, and folders.312MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read and write to OmniFocus database, allowing natural language task management, project creation, and GTD workflows.41MIT
- AlicenseBqualityDmaintenanceEnables Codex to interact with the user's local OmniFocus database on macOS, allowing task management, project creation, and tag operations through natural language.21MIT
- AlicenseAqualityDmaintenanceEnables task management in OmniFocus, including reading, creating, updating, and completing tasks, with automatic detection of Pro or Standard version.711 npmMIT