Omnifocus MCP

🚀 OmniFocus MCP 服務器

這是一個用於將 OmniFocus 與 Claude Desktop 集成的模型上下文協議（MCP）服務器。該服務器使 Claude 能夠訪問你的 OmniFocus 任務和項目，實現由人工智能驅動的任務管理和每週回顧。

✨ 主要特性

• 🎯 OmniFocus 集成 - 可訪問 OmniFocus 中的任務和項目。
• 🔧 活躍任務過濾 - 僅獲取未完成的任務，排除模板和系統項。
• 🚀 TypeScript + MCP SDK - 類型安全且易於維護。
• 🔒 安全自動化 - 使用官方 Omni Automation JavaScript API。
• 📱 Claude Desktop 適配 - 與 Claude Desktop 無縫協作。

🛠️ 當前工具

omnifocus:get_all_tasks

通過過濾選項從 OmniFocus 中檢索所有任務：

• includeCompleted（布爾值） - 是否包含已完成的任務（默認：false）
• limit（數字） - 要返回的最大任務數（默認：100）

omnifocus:get_active_tasks

僅檢索活躍（未完成）的任務，自動過濾掉：

• “模板”文件夾中的任務。
• 包含模板佔位符（«，»）的任務。
• 帶有同步偏好標記（⚙️）的任務。

omnifocus:get_projects

從 OmniFocus 中檢索所有活躍的項目。

📋 前提條件

• 安裝了 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 獲取我所有的活躍任務”
• “顯示我的項目”
• “我今天有哪些任務？”
• “幫助我進行每週回顧”

🔧 技術細節

核心組件

• 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 文檔。
• 在本倉庫中創建一個問題。