OmniFocus MCP Server

一个 Model Context Protocol (MCP) 服务器，使 AI 助手能够通过 JXA (JavaScript for Automation) 与 macOS 上的 OmniFocus 交互。

功能

此 MCP 服务器提供对 OmniFocus 功能的访问：

任务管理

• 列出收件箱任务 - 查看并筛选收件箱中的任务（支持多标签筛选）

• 创建任务 - 添加新任务，支持完整属性（截止日期、计划日期、标签、备注、子任务、重复）

• 更新任务 - 更改名称、备注、日期、旗标、预估时长、重复规则，或将任务移至其他项目

• 完成/放弃任务 - 将任务标记为完成或已放弃，支持单个或批量操作

• 删除任务 - 永久移除任务

• 更新任务备注 - 替换、清空或追加任务的备注

• 获取到期任务 - 查找在某个时间段内到期的任务

• 获取计划任务 - 查找在某个时间段内计划的任务

• 获取旗标任务 - 列出所有带旗标的项目

• 为任务添加/移除标签 - 管理任务标签，支持单个或批量操作

项目管理

• 列出项目 - 查看项目并支持按状态筛选

• 获取项目任务 - 列出某项目下的所有任务

• 创建项目 - 创建新项目，可设置所在文件夹、状态、日期、顺序模式、复核间隔

• 更新项目 - 更改名称、备注、状态、旗标、日期、顺序模式、复核间隔

• 删除项目 - 移除项目及其所有任务

• 更新项目备注 - 替换、清空或追加项目备注

• 获取待审核项目 - 查找需要复核的项目，可选择包含其未完成任务

• 将项目标记为已复核 - 更新项目的复核状态和下次复核日期

• 批量标记已复核 - 一次高效复核多个项目

组织

• 列出文件夹 - 查看文件夹层级

• 创建/重命名/删除文件夹 - 管理文件夹树（包括嵌套文件夹）

• 列出标签 - 查看所有标签

• 列出透视图 - 查看内置和自定透视图

• 获取透视图任务 - 列出特定透视图中的任务

搜索

• 全局搜索 - 跨任务、项目、文件夹和标签搜索

安全性

• 重复名称不会被静默处理。 OmniFocus 允许两个项目（或任务）使用相同名称。名称查找会收集所有匹配项，并在有多个匹配项时连同匹配项的 ID 一起失败，因此重命名、移动或删除绝不会在误操作了错误目标后仍成功。

• 变更会经过验证。 JXA 可能静默失败的操作（尤其是将任务移动到其他项目）会在同一脚本内回读结果，因此失败将失败操作为错误而不是成功。

Related MCP server: OmniFocus MCP Server

系统要求

• macOS（OmniFocus 仅支持 macOS/iOS，而此服务器使用 JXA）

• 已安装 OmniFocus 3+

• Node.js 18+

• 为您的终端/客户端应用启用 自动化权限

安装

1. 克隆或下载此仓库：

   cd omnifocus-mcp-server

2. 安装依赖：

   npm install

3. 构建 TypeScript：

   npm run build

4. 配置您的 MCP 客户端使用该服务器（参见下方“配置”）

配置

Claude Desktop

将以下内容添加到您的 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "omnifocus": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/omnifocus-mcp-server/dist/index.js"]
    }
  }
}

使用 node 二进制文件的绝对路径。仅使用 "node" 会根据图形会话的 PATH 进行解析，而该 PATH 不包含 Homebrew 或版本管理器的 shim，因此即使服务器能在终端中正常启动，也可能造成“服务器无法访问”的错误。使用 which node 查找您的路径。

Other MCP Clients

服务器默认使用 stdio 传输，因此请将客户端配置为启动：

node /path/to/omnifocus-mcp-server/dist/index.js

Remote access (HTTP transport)

对于远程客户端，尤其是 claude.ai 的自定义连接器（这是 Claude iOS 应用连接 MCP 服务器的方式），服务器可作为一个 Streamable HTTP 端点运行：

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
node /path/to/omnifocus-mcp-server/dist/index.js

环境变量：

MCP 端点为 /mcp。认证接受 Authorization: Bearer <token> 头，或用于无法发送自定义头的客户端，可将令牌作为路径段（/mcp/<token>）。GET /health 不进行认证。

从 claude.ai / iOS App 访问。 自定义连接器从 Anthropic 的云（而非您的设备）建立连接，因此端点必须被公开 HTTPS 可达。Cloudflare Tunnel 或 Tailscale Funnel 都可以满足——这两种方式实际上都是由本地进程发起出站连接，因此无需打开端口。（仅 Tailscale 而不带 Funnel 不行：它只会达到您自己的 tailnet，而 Anthropic 的云不在其中。）可选，可在 Cloudflare WAF 规则中限制为 Anthropic 的出站 IP 范围（160.79.104.0/21）。

claude.ai 和 Claude Desktop 的“连接器” UI（相对于直接的 MCP 配置/ API 客户端）总会在其调用远程服务器之前执行完整的 OAuth 握手——它不接受静态令牌本身，即使将其嵌入 URL 也一样。设置 MCP_PUBLIC_URL 后，您的隧道公共源会自我颁发 OAuth 层，同时仍然使用相同的静态密钥限制访问（参见 oauth.ts / CLAUDE.md 来了解详情）。设置后，在 Settings → Connectors 中使用路径令牌 URL（https://your-tunnel-host/mcp/<token>）添加连接器——“连接”步骤将自动完成 OAuth 握手。如果您的隧道也将 / 代理到另一个本地服务，请确保 /authorize、/token、/register 和 /.well-known/* 也映射到该服务器，否则 OAuth 请求将永远不会到达这里。

Mac 必须保持唤醒并运行 OmniFocus（caffeinate -s 或 Amphetamine）。

Session semantics — single client only. HTTP 传输仅服务一个会话：新的 initialize 会替换先前的会话。每个工具调用本身都是原子的，符合规范的新客户端会使当 404 时重新初始化，因此单个客户端按顺序调用即可正常工作。这个 404；在服务器重启后，每个客户端都会遇到“无会话”这个情况——它们会重新初始化，而不是将其视为死节点。

多个客户端同时连接并不可行。不需要在两个并发 initialize→tools/list 序列上复制它：另一个始终会 404。底层 MCP SDK 将单个传输绑定到服务器实例，因此丢失的会话被驱逐，并且在途请求不是 404 就是挂起。修复方案是让每个会话都有一个 McpServer 实例，而不是在共享的单例上注册。目前计划中不包含此改动。详见 CLAUDE.md。

排查“无法连接”客户端。 客户端将所有远程故障折叠为一个模糊的消息，因此应查看服务器日志（您启动代理的 StandardErrorPath），而不是客户端的措辞。状态代码表示以下三种无关情况之一：

如果日志中完全无条目，说明请求从未到达服务器：检查隧道的路径映射，而不是此代码。

权限

首次使用时，macOS 将提示您允许自动化访问：

1. 进入 系统偏好设置 → 安全性隐私 → 隐私 → 自动化

2. 为您的终端或 Claude Desktop 启用控制 OmniFocus 的权限

工具参考

以下按功能区域列出了全部 31 个工具。

函数名称

omnifocus_list_inbox

Description: List tasks in the inbox, optionally filtered by tags.

{
  "includeCompleted": false,
  "limit": 50,
  "tags": ["Work", "Urgent"],
  "tagMatchMode": "all"
}

标签匹配模式 可选为 "all"（任务具有所列出的所有标签，默认）、"any"（至少具有一个）或 "none"（均没有）。仅在 tags 参数存在时有效。同样的两个参数也用于 omnifocus_get_due_tasks、omnifocus_get_flagged_tasks 和 omnifocus_get_planned_tasks。

omnifocus_list_projects

Description: List projects with filtering.

{
  "status": "active",
  "folderName": "Work",
  "limit": 50
}

omnifocus_get_project_tasks

Description: Get all tasks belonging to one project.

{
  "projectId": "abc123",
  "includeCompleted": false,
  "limit": 100
}

omnifocus_create_project

Description: Create a project, optionally inside a folder.

{
  "name": "Website redesign",
  "note": "Q1 initiative",
  "folderName": "Work",
  "dueDate": "2024-03-31T17:00:00",
  "deferDate": "2024-01-15T09:00:00",
  "flagged": false,
  "sequential": false,
  "status": "active",
  "reviewIntervalDays": 7
}

status 为 "active"（默认）、"on hold"、"done" 或 "dropped"。sequential: false（默认）创建并行项目。

omnifocus_update_project

更新项目属性。通过 projectId 或 projectName 标识（ID 优先）。

{
  "projectId": "abc123",
  "name": "Website redesign v2",
  "status": "on hold",
  "flagged": true,
  "dueDate": null,
  "sequential": true,
  "reviewIntervalDays": 14
}

将 null 传给 note、dueDate 或 deferDate 可清除相应内容。项目不能移动到其他文件夹（JXA 限制）。

omnifocus_delete_project

删除项目及其任务。通过 projectId 或 projectName 标识（ID 优先）。

{
  "projectId": "abc123"
}

omnifocus_list_folders

列出所有文件夹。

{
  "status": "active",
  "limit": 50
}

omnifocus_create_folder

创建文件夹，可创建在顶层或嵌套层级。

{
  "name": "Clients",
  "parentFolderName": "Work"
}

omnifocus_update_folder

重命名文件夹。通过 folderId 或 folderName 标识（ID 优先）。文件夹不能移动到其他文件夹中（JXA 限制）。

{
  "folderName": "Clients",
  "name": "Key clients"
}

omnifocus_delete_folder

删除文件夹及其中的所有内容。通过 folderId 或 folderName 标识（ID 优先）。

{
  "folderId": "abc123"
}

omnifocus_list_tags

列出所有标签。

{
  "status": "active",
  "limit": 50
}

omnifocus_list_perspectives

列出视角（内置和自定义）。

{
  "limit": 50
}

omnifocus_get_perspective_tasks

获取特定视角中显示的任务。

{
  "perspectiveName": "Next",
  "limit": 50
}

omnifocus_create_task

创建新任务。

{
  "name": "Review quarterly report",
  "note": "Check all sections",
  "projectName": "Work",
  "dueDate": "2024-12-31T17:00:00",
  "deferDate": "2024-12-01T09:00:00",
  "plannedDate": "2024-12-15T09:00:00",
  "flagged": true,
  "estimatedMinutes": 60,
  "tagNames": ["Review", "Important"],
  "parentTaskId": "xyz789",
  "recurrence": {
    "frequency": "weekly",
    "interval": 1,
    "daysOfWeek": ["Monday", "Thursday"],
    "repeatFrom": "due-date"
  }
}

计划日期与截止日期：

• dueDate：任务必须完成的日期（截止时间）

• plannedDate：您计划处理该任务的日期（计划时间）

• 区分这两者对于规划至关重要

重复规则：frequency 为 "daily"、"weekly"、"monthly" 或 "yearly"。每周使用 daysOfWeek，每月使用 dayOfMonth（1-31），每年使用 monthOfYear（1-12）。repeatFrom 为 "due-date"（默认）或 "completion-date"。

子任务： 传入 parentTaskId 可将任务作为现有任务的子任务创建。

omnifocus_update_task

更新现有任务。通过 taskId 或 taskName 标识（ID 优先）。

{
  "taskId": "abc123",
  "name": "Review quarterly report (final)",
  "note": null,
  "dueDate": "2024-12-20T17:00:00",
  "flagged": true,
  "estimatedMinutes": 45,
  "projectName": "Work"
}

• 为 note、dueDate、deferDate 或 plannedDate 传入 null 可清除它们；estimatedMinutes: 0 可清除估算时间。

• 使用 projectId 或 projectName 移动任务到该项目（子任务随行）。移动后会被验证，因此失败会报错而不是假成功。

• recurrence 接受与 create_task 相同的对象；recurrence: null 或 clearRecurrence: true 可关闭重复。

omnifocus_delete_task

删除任务。通过 taskId 或 taskName 识别（ID 优先）。

{
  "taskId": "abc123"
}

omnifocus_update_task_note

替换、清空或追加任务备注。通过 taskId 或 taskName 识别（ID 优先）。

{
  "taskId": "abc123",
  "note": "Added after the call.",
  "append": true
}

空的 note 字符串将清空备注。

omnifocus_complete_task

将任务标记为完成或放弃。可以通过 ID 或名称来标识任务。

{
  "taskId": "abc123",
  "action": "complete"
}

或者使用任务名称：

{
  "taskName": "Write documentation",
  "action": "complete"
}

操作可为 "complete"（默认）或 "drop"。如果同时提供了 taskId 和 taskName，则以 taskId 为准。

放弃重复任务时，会先清除其重复规则，这样系列就会真正停止，而不会继续滚动到下一次。

omnifocus_batch_complete_task

在一次调用中按 ID 完成或放弃最多 100 个任务。

{
  "taskIds": ["id1", "id2", "id3"],
  "action": "complete"
}

omnifocus_add_tag_to_task

向任务添加标签。你可以通过 ID 或名称来标识任务。

{
  "taskId": "abc123",
  "tagName": "Urgent"
}

或使用任务名称：

{
  "taskName": "Write report",
  "tagName": "Urgent"
}

如果同时提供了 taskId 和 taskName，则以 taskId 为准。

omnifocus_remove_tag_from_task

从任务中移除标签。你可以通过 ID 或名称来标识任务。

{
  "taskId": "abc123",
  "tagName": "Urgent"
}

或使用任务名称：

{
  "taskName": "Old task",
  "tagName": "Done"
}

如果同时提供了 taskId 和 taskName，则以 taskId 为准。

omnifocus_batch_add_tag

通过 ID 为一个标签批量添加到最多 100 个任务。

{
  "taskIds": ["id1", "id2", "id3"],
  "tagName": "Urgent"
}

omnifocus_batch_remove_tag

通过 ID 从最多 100 个任务中批量移除一个标签。

{
  "taskIds": ["id1", "id2", "id3"],
  "tagName": "Urgent"
}

omnifocus_update_project_note

替换、清除或追加项目的备注。通过 projectId 或 projectName 标识（ID 优先）。

{
  "projectName": "Website redesign",
  "note": "Kickoff moved to March.",
  "append": false
}

omnifocus_search

跨 OmniFocus 搜索。

{
  "query": "report",
  "searchType": "all",
  "limit": 20
}

omnifocus_get_due_tasks

获取在指定时间范围内到期的任务。

{
  "daysAhead": 7,
  "includeOverdue": true,
  "limit": 50
}

omnifocus_get_flagged_tasks

获取已标记旗标的任务。

{
  "includeCompleted": false,
  "limit": 50
}

omnifocus_get_planned_tasks

获取在指定时间范围内计划的任务。

{
  "daysAhead": 7,
  "includeOverdue": true,
  "limit": 50
}

omnifocus_get_projects_for_review

根据下次审核日期获取待审核的项目。非常适合遵循 GTD 审核流程的用户。

{
  "daysAhead": 0,
  "status": "active",
  "limit": 50,
  "includeTasks": true,
  "taskLimit": 50
}

参数：

• daysAhead：向前查看的天数（0 = 仅查看逾期的审核）

• status：按项目状态筛选（"active"、"done"、"dropped"、"onHold"、"all"）

• limit：返回的最大项目数（1-500）

• includeTasks：是否在结果中包含每个项目的未完成任务（默认 false）——开启后可将一次审核流程从每个项目一次后续调用减少为一次调用

• taskLimit：当 includeTasks 为 true 时，每个项目返回的最大任务数（1-500）

每个项目还会返回 reviewInterval 和 lastReviewDate。

omnifocus_mark_project_reviewed

将项目标记为已审核，并更新其下次审核日期。您可以通过 ID 或名称标识项目。

{
  "projectId": "abc123"
}

或使用项目名称：

{
  "projectName": "Weekly Review"
}

使用自定义审核间隔：

{
  "projectName": "Work Project",
  "reviewIntervalDays": 14
}

参数：

• projectId 或 projectName：标识项目（ID 优先）

• reviewIntervalDays（可选）：自定义审核间隔天数。如果未提供，则使用项目的现有审核间隔。

omnifocus_get_tasks_due

获取在指定时间范围内到期的任务。

{
  "projectIds": ["id1", "id2", "id3"]
}

omnifocus_get_tasks_flagged

获取已标记的任务。

{
  "projectIds": ["id1", "id2", "id3"],
  "reviewIntervalDays": 7
}

omnifocus_get_tasks_completed

获取在指定时间范围内完成的任务。

npm run build

omnifocus_get_tasks_dropped

获取在指定时间范围内放弃的任务。

npm run dev

omnifocus_get_tasks_in_project

获取项目中的任务。通过 projectId 或 projectName 标识（ID 优先）。

npm test              # All unit tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report (thresholds enforced: 80% lines, 75% branches)

omnifocus_get_tasks_matching_name

通过名称匹配获取任务。支持部分匹配和通配符匹配（*）。

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

omnifocus_get_tasks_matching_name

通过名称匹配获取任务。支持部分匹配和通配符匹配。

GXP48