OmniFocus MCP服务器
一个与OmniFocus集成的模型上下文协议（MCP）服务器，使Claude（或其他兼容MCP的客户端）能够与您的任务和项目进行交互。
概述
此MCP服务器在AI助手（如Claude）和OmniFocus任务管理系统之间建立了一座桥梁。它使AI模型能够通过自然语言对话查看、创建、编辑和删除OmniFocus数据库中的任务和项目。 您可以使用它的一些方法：
- 将教学大纲的PDF翻译成一个完全指定的项目，其中包含任务、标签、推迟日期和截止日期。
- 将会议记录转化为行动列表
- 创建任务、项目和标签的可视化
- 在单个操作中处理多个任务或项目
- 高效地批量管理您的OmniFocus项目
路线图
- 添加MCP
prompt特征 - 支持操纵项目和任务的通知
- 请参阅 GitHub问题 用于功能请求和已知问题
快速开始
先决条件
- 安装了OmniFocus的macOS
连接到克劳德
- 在Claude Desktop中，将此MCP服务器添加到您的配置文件中：
1~/Library/Application Support/Claude/claude_desktop_config.json- 添加以下配置：
JSON``` 1 2 3 4 5 6 7 8{ “mcpServers”: { “omnifocus”: { “command”: “npx”, “args”: [“-y”, “omnifocus-mcp”] } } }
1. 重新启动克劳德桌面
## 用例
### 高效的任务查询
使用新 `query_omnifocus` 快速、有针对性的搜索工具：
> “显示今天到期的任务”
> “获取我的工作项目中的所有标记项”
>
> “计算每个项目中有多少任务”
### 重新组织您的项目、任务和标签
> “我希望每个任务都有一个能量水平标签。给我一份没有能量水平标签的所有任务的列表，以及你对添加哪个标签的建议。我会做出我认为合适的任何更改。然后在OmniFocus中进行更改。”
### 从任何对话中添加任务
> “好的，感谢您详细解释为什么法治很重要。在我的激进主义项目中添加一个重复任务，提醒我每周给我的代表打电话。在笔记字段中包含这次对话的摘要。”
### 快速、虚拟视角
获取当前任务的摘要，并通过对话方式进行管理：
> “显示本周到期的所有标记任务”
或创建自定义视图：
> “我在“工作”文件夹中的下一步操作是什么？”
### 使用OmniFocus视角
列出并查看您的观点：
> “我有什么观点？”
> “显示收件箱透视图中的内容”
> “从我当前的视角获取标记的项目”
### 过程成绩单或PDF
从会议记录、学术研究文章或笔记中提取行动项目：
> “我正在粘贴今天会议的记录。请分析它，并在OmniFocus中为分配给我的任何行动项创建任务。将它们放在我的‘产品开发’项目中。”
## 资源
资源允许MCP客户端将OmniFocus数据作为上下文预加载，而无需调用工具。支持MCP资源的客户端（如Claude Desktop）可以将这些资源直接附加到对话中。
### 固定资源
| URI | 描述 |
| --- | --- |
| `omnifocus://inbox` | 当前收件箱项目（未分配给任何项目的任务） |
| `omnifocus://today` | 今天的议程——今天到期的任务、今天计划的任务和逾期的任务 |
| `omnifocus://flagged` | 所有标记的项目 |
| `omnifocus://stats` | 快速数据库统计（任务计数、项目计数、逾期等） |
### 模板资源
| URI模式 | 描述 |
| --- | --- |
| `omnifocus://project/{name}` | 特定项目中的任务（支持自动完成） |
| `omnifocus://perspective/{name}` | 在命名透视图中可见的项目（支持自动补全） |
所有资源返回JSON(`application/json`).模板资源支持列出所有可用值并自动完成 `{name}` 参数。
## 可用工具
服务器目前提供以下工具：
### `query_omnifocus`
使用强大的过滤器高效查询OmniFocus数据库。在不加载整个数据库的情况下获取特定任务、项目或文件夹。
主要特点：
- **按多个条件筛选**：项目、标记、状态、截止日期、标志、注释等
- **请求特定字段**：通过只获取所需的数据来减少响应大小
- **对结果进行排序和限制**：控制输出格式
- **比dump_database快得多** 用于有针对性的查询
常见用途：
1 2 3 4”Show me all flagged tasks due this week” “Get next actions from my Work project” “Count tasks in each project” (use with summary: true) “Find all tasks deferred until tomorrow”
参数：
- `entity`：键入要查询的内容（“任务”、“项目”或“文件夹”）
- `filters`：（可选）按项目、标签、状态、日期等缩小结果范围。
- `projectName`, `projectId`, `folderId`：按容器过滤
- `tags`：按标签名称筛选（OR逻辑，区分大小写）
- `status`：按状态筛选（OR逻辑）
- `flagged`：按标记状态筛选
- `inbox`：按收件箱状态筛选（true=仅收件箱，false=排除收件箱）
- `dueWithin`, `deferredUntil`, `plannedWithin`：范围日期筛选器（从今天开始的天数）
- `dueOn`, `deferOn`, `plannedOn`：精确日期过滤器（0=今天，1=明天等）
- `hasNote`：按钞票存在情况过滤
- `fields`：（可选）要返回的特定字段（id、name、note、dueDate等）
- `limit`：（可选）可退回的最大项目数
- `sortBy`：（可选）排序依据的字段
- `includeCompleted`：（可选）包括已完成的项目（默认值：false）
- `summary`：（可选）仅返回计数，不返回完整详细信息
### `dump_database`
获取OmniFocus数据库的完整当前状态。最适合进行全面分析或需要一切时使用。
参数：
- `hideCompleted`：（可选）隐藏已完成/已删除的任务（默认值：true）
- `hideRecurringDuplicates`：（可选）隐藏重复的定期任务（默认值：true）
### `add_omnifocus_task`
向OmniFocus添加新任务。
参数：
- `name`：任务的名称
- `projectName`：（可选）要将任务添加到的项目的名称
- `note`：（可选）任务的其他注释
- `dueDate`：（可选）ISO格式的任务截止日期
- `deferDate`：（可选）ISO格式的任务延迟日期
- `plannedDate`：（可选）ISO格式的任务计划日期-表示打算在此日期处理此任务
- `flagged`：（可选）是否标记任务
- `estimatedMinutes`：（可选）完成任务的估计时间
- `tags`：（可选）要分配给任务的标签
- `parentTaskId`：（可选）按ID在现有父任务下创建
- `parentTaskName`：（可选）按名称在第一个匹配的父任务下创建（回退）
### `add_project`
向OmniFocus添加新项目。
参数：
- `name`：项目名称
- `folderName`：（可选）要将项目添加到的文件夹的名称
- `note`：（可选）项目的附加说明
- `dueDate`：（可选）ISO格式的项目截止日期
- `deferDate`：（可选）ISO格式的项目推迟日期
- `flagged`：（可选）是否标记项目
- `estimatedMinutes`：（可选）完成项目的估计时间
- `tags`：（可选）要分配给项目的标记
- `sequential`：（可选）项目中的任务是否应按顺序执行
### `remove_item`
从OmniFocus中删除任务或项目。
参数：
- `id`：（可选）要删除的任务或项目的ID
- `name`：（可选）要删除的任务或项目的名称
- `itemType`：要删除的项目类型（“任务”或“项目”）
### `edit_item`
在OmniFocus中编辑任务或项目。
参数：
- `id`：（可选）要编辑的任务或项目的ID
- `name`：（可选）要编辑的任务或项目的名称
- `itemType`：要编辑的项目类型（“任务”或“项目”）
- 用于编辑属性的各种参数
### `batch_add_items`
在单个操作中将多个任务或项目添加到OmniFocus。
参数：
- `items`：要添加的项目数组，其中每个项目可以是：
- `type`：项目类型（“任务”或“项目”）
- `name`：项目的名称
- `note`：（可选）附加注释
- `dueDate`：（可选）ISO格式的截止日期
- `deferDate`：（可选）ISO格式的延迟日期
- `plannedDate`：（可选）ISO格式的计划日期（仅限任务）
- `flagged`：（可选）是否标记项目
- `estimatedMinutes`：（可选）预计完成时间
- `tags`：（可选）标签数组
- `projectName`：（可选）对于任务：要添加到的项目
- `folderName`：（可选）对于项目：要添加到的文件夹
- `sequential`：（可选）对于项目：任务是否按顺序排列
- `parentTaskId`：（可选，任务）：按ID列出的父任务
- `parentTaskName`：（可选，任务）：按名称列出父任务（回退）
- `tempId`：（可选，任务）：批内引用的临时ID
- `parentTempId`：（可选，任务）：引用另一个项目的 `tempId` 建立等级制度
- `hierarchyLevel`：（可选，任务）：排序提示（0表示根，1表示子，…）
示例：
1 2 3 4 5 6 7 8{ “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`
在一次操作中从OmniFocus中删除多个任务或项目。
参数：
- `items`：要删除的项目数组，其中每个项目可以是：
- `id`：（可选）要删除的项目的ID
- `name`：（可选）要删除的项目的名称
- `itemType`：项目类型（“任务”或“项目”）
### `list_perspectives`
列出OmniFocus中所有可用的透视图，包括内置和自定义透视图。
参数：
- `includeBuiltIn`：（可选）包括收件箱、项目、标签等内置透视图（默认值：true）
- `includeCustom`：（可选）包括自定义透视图（专业功能）（默认值：true）
退货：
- 透视图及其名称、类型（内置/自定义）以及是否可以修改的列表
### `get_perspective_view`
使项目在当前OmniFocus透视图中可见。显示显示的任务和项目。
参数：
- `perspectiveName`：要查看的透视图的名称（例如，“收件箱”、“项目”、“标记”）
- `limit`：（可选）要返回的最大项目数（默认值：100）
- `includeMetadata`：（可选）包括其他元数据，如标签和日期（默认值：true）
- `fields`：（可选）要包含在响应中的特定字段
注意：此工具返回当前透视窗口的内容。由于OmniJS的限制，它不能以编程方式切换视角。
### `list_tags`
列出OmniFocus中的所有标签及其层次结构。可用于在创建或编辑任务之前发现可用标签。
参数：
- `includeDropped`：（可选）包括已删除/未激活的标签（默认值：false）
退货：
- 带有名称、ID、父层次结构、活动状态和任务计数的标记列表
## 服务器说明和日志记录
### 服务器说明
服务器在初始化握手期间向MCP客户端提供内置指令。这些指导人工智能助手选择工具（例如，偏好 `query_omnifocus` 结束 `dump_database`)、可用资源和查询过滤器提示——无需用户配置。
### 结构化日志记录
服务器通过MCP日志协议发出结构化日志消息。客户端可以设置最低日志级别(`debug`, `info`, `warning`, `error`等）使用 `logging/setLevel` 请求。脚本执行时间和错误会自动记录。
## 运作原理
此服务器使用JXA（JavaScript for Automation）通过以下方式与OmniFocus通信 `osascript`，允许它与应用程序的本机功能进行交互。服务器是使用 [模型上下文协议SDK](https://github.com/modelcontextprotocol/sdk)，为人工智能模型与外部工具和系统交互提供了一种标准化的方式。
有关查询工具使用的详细信息，请参阅 查询_工具_参考.md 和 查询_对象_示例.md.
## 贡献
欢迎投稿！请随时提交拉取请求。