金大哥 - omnifocus-mcp MCP 详情

article

README

🚀 OmniFocus MCP 服务器

这是一个用于将 OmniFocus 与 Claude Desktop 集成的模型上下文协议（MCP）服务器。该服务器允许 Claude 访问你的 OmniFocus 任务和项目，从而实现由人工智能驱动的任务管理和每周回顾。

✨ 主要特性

🎯 OmniFocus 集成：可访问 OmniFocus 中的任务和项目。
🔧 活跃任务过滤：仅获取未完成的任务，排除模板和系统项目。
🚀 TypeScript + MCP SDK：类型安全且易于维护。
🔒 安全自动化：使用官方的 Omni Automation JavaScript API。
📱 适配 Claude Desktop：与 Claude Desktop 无缝协作。

📦 安装指南

前提条件

安装了 OmniFocus 的 macOS 系统。
Node.js 23.10.0 或更高版本。
Claude Desktop 应用程序。
OmniFocus 的自动化权限。

安装步骤

克隆仓库：

git clone https://github.com/mdoel/omnifocus-mcp
cd omnifocus-mcp

安装依赖：
```
npm install
```
构建项目：
```
npm run build
```
配置 Claude Desktop：

将以下内容添加到你的 Claude Desktop MCP 配置中：
```
{
  "mcpServers": {
    "omnifocus": {
      "command": "/path/to/omnifocus/run-server.sh",
      "args": []
    }
  }
}
```
重要提示：请将 /path/to/omnifocus/ 替换为你项目目录的实际路径。
授予自动化权限：

首次运行服务器时，macOS 会提示你授予 OmniFocus 自动化权限。请在提示时点击“允许”。

注意：如果你遇到权限问题，可能需要临时取消 run-server.sh 中 osascript 行的注释以触发权限对话框。授予权限后，再次注释掉这些行，以免每次启动时都弹出对话框。
重启 Claude Desktop 以加载新的 MCP 服务器。

💻 使用示例

基础用法

配置完成后，你可以向 Claude 提出以下请求：

“从 OmniFocus 获取我所有的活跃任务”
“显示我的项目”
“我今天有哪些任务？”
“帮我进行每周回顾”

📚 详细文档

当前工具

`omnifocus:get_all_tasks`

从 OmniFocus 检索所有任务，并支持过滤选项：

includeCompleted（布尔值）：是否包含已完成的任务（默认值：false）
limit（数字）：返回的最大任务数（默认值：100）

`omnifocus:get_active_tasks`

仅检索活跃（未完成）任务，自动过滤掉以下任务：

“模板”文件夹中的任务
包含模板占位符（«, »）的任务
带有同步偏好标记（⚙️）的任务

`omnifocus:get_projects`

从 OmniFocus 检索所有活跃项目。

🔧 技术细节

核心组件

OmniFocusClient：通过 Omni Automation 处理与 OmniFocus 的通信。
OmniFocusJXA：用于构建和执行 JXA 脚本的实用工具。
OmniFocusMCPServer：主要的 MCP 服务器实现。

目录结构

src/
├── index.ts              # 主入口点
├── server.ts             # MCP 服务器实现
├── omnifocus/
│   ├── client.ts         # OmniFocus 自动化客户端
│   └── omnifocus-jxa.ts  # JXA 脚本实用工具
└── types/
    └── omnifocus.ts      # TypeScript 定义

开发相关

构建项目

# 构建项目
npm run build

# 开发模式下的监听模式
npm run dev

测试

你可以在本地测试服务器：

# 使用命令行参数进行测试
node dist/index.js all        # 获取所有任务
node dist/index.js active     # 仅获取活跃任务
node dist/index.js projects   # 仅获取项目

测试 OmniFocus 自动化

直接测试 OmniFocus 自动化：

# 测试基本连接
osascript -l JavaScript -e "Application('OmniFocus').running()"

# 测试任务检索
osascript -l JavaScript -e "
const app = Application('OmniFocus');
const doc = app.defaultDocument;
const tasks = doc.flattenedTasks();
console.log('Found ' + tasks.length + ' tasks');
"

故障排除

服务器连接问题

如果 Claude Desktop 无法连接到服务器：

检查脚本路径：确保你在 Claude Desktop 配置中的脚本路径正确。
验证权限：确保 run-server.sh 脚本具有可执行权限：
```
chmod +x run-server.sh
```
检查 Node.js 安装：确保已安装 Node.js 23.10.0 或更高版本。
查看日志：检查 Claude Desktop 的 MCP 服务器日志以获取错误信息。

权限问题

如果你遇到自动化权限错误：

打开 系统偏好设置 > 安全性与隐私 > 隐私。
从左侧边栏中选择 自动化。
找到你的终端/ shell 并勾选 OmniFocus。
重启终端并再次尝试。

未找到 OmniFocus

确保已安装并运行 OmniFocus。
验证应用程序名称为“OmniFocus”（而不是“OmniFocus 3”或其他类似名称）。
检查 OmniFocus 未被放入废纸篓或禁用。

性能问题

如果服务器运行缓慢或超时：

服务器处理大型 OmniFocus 数据库可能需要一些时间。
考虑使用 limit 参数减少返回的任务数量。
确保 OmniFocus 未执行其他操作。

贡献代码

本项目设计为可扩展的。若要添加新功能，请按以下步骤操作：

在 src/omnifocus/ 目录中 添加新工具。
更新服务器 以注册新工具。
使用你的 OmniFocus 数据进行 全面测试。
提交带有清晰文档的 拉取请求。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

如果你遇到问题或有疑问：

查看上述故障排除部分。
查阅 Claude Desktop MCP 文档。
在本仓库中提交问题。

omnifocus-mcp