Omnifocus MCP

🚀 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 的自动化权限。

安装步骤

1. 克隆仓库：

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

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

4. 配置 Claude Desktop：

   将以下内容添加到你的 Claude Desktop MCP 配置中：

   {
     "mcpServers": {
       "omnifocus": {
         "command": "/path/to/omnifocus/run-server.sh",
         "args": []
       }
     }
   }
   

   重要提示：请将 /path/to/omnifocus/ 替换为你项目目录的实际路径。

5. 授予自动化权限：

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

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

6. 重启 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 无法连接到服务器：

1. 检查脚本路径：确保你在 Claude Desktop 配置中的脚本路径正确。
2. 验证权限：确保 run-server.sh 脚本具有可执行权限：

   chmod +x run-server.sh
   

3. 检查 Node.js 安装：确保已安装 Node.js 23.10.0 或更高版本。
4. 查看日志：检查 Claude Desktop 的 MCP 服务器日志以获取错误信息。

权限问题

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

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

未找到 OmniFocus

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

性能问题

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

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

贡献代码

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

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

📄 许可证

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

支持

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

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