Skip to main content
Glama
omnifocus-mcp
by steveardis

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"]
    }
  }
}

可用工具

读取

工具

描述

list_projects

项目,可按 status、folderId、flagged 过滤。默认排除已完成/已丢弃。限制(默认 100)。

get_project

通过稳定 ID 获取完整的项目详情

list_tasks

任务,按 projectId、folderId、inbox: true 或 all: true 限定范围,并支持可选的 status/tag/due/flagged 过滤。限制(默认 200)。

get_task

通过稳定 ID 获取完整任务详情——包括 defer/planned/due 日期、标签、重复规则、parentTaskId

list_folders

文件夹,可按状态过滤。限制(默认 200)。

get_folder

通过稳定 ID 获取完整文件夹详情,包括子文件夹和项目 ID

list_tags

标签,可按状态过滤。限制(默认 200)。

get_tag

通过稳定 ID 获取完整标签详情,包括子标签 ID

resolve_name

将名称解析为稳定 ID 候选——绝不静默消歧;返回所有匹配结果

写入

工具

描述

create_task

在收件箱、项目中创建任务,或创建为子任务。支持 defer/planned/due 日期、标签、flagged、预计分钟数和重复规则。

edit_task

编辑任意任务字段。传入 null 以清除日期或重复规则。省略的字段保持不变。

complete_task

将任务标记为已完成

drop_task

将任务标记为已丢弃

delete_task

永久删除任务及所有子任务

create_project

创建项目,可选择在文件夹中创建。支持类型、状态、审查间隔、标签。

edit_project

编辑项目字段

complete_project

将项目标记为已完成

drop_project

将项目标记为已丢弃

delete_project

永久删除项目及其所有任务

create_folder

创建文件夹,可选择嵌套创建

edit_folder

重命名文件夹

delete_folder

永久删除文件夹及其整个子树

create_tag

创建标签,可选择嵌套创建

edit_tag

编辑标签名称或状态

delete_tag

永久删除标签及子标签

move_task

将任务移动到项目,或作为另一个任务的子任务

move_project

将项目移动到文件夹或顶层

寻址模型

此服务器返回的每个实体都包含一个稳定的 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

Available Tools

27 tools
complete_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

    A3.7/5.0

    Scored across 27 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers