OmniFocus MCP 服务器（FastMCP 实现）

使用说明（Markdown 格式）

• 项目简介

  • 该仓库实现了一个基于 MCP 的服务器端，专门用于与 OmniFocus（macOS 应用）进行对接，向基于大型语言模型的客户端提供上下文信息、数据访问和外部功能调用能力。核心组件包括资源/数据访问、工具执行、提示模板渲染等，统一通过 JSON-RPC 进行请求/响应。

• 主要功能点

  • MCP 服务器核心能力实现：托管和管理资源（如项目、任务、文件夹、标签等），提供数据访问能力；注册并执行 Tools，允许 LLM 调用外部功能；定义并渲染 Prompts，支持可定制的交互模式。
  • 服务器端会话管理和能力声明，支持通过多种传输协议（如标准 MCP 端口/管道通信场景）对接客户端。
  • 包含服务器端命令实现（如 get_tasks、get_projects、create_task、update_task、delete_tasks、update_projects 等等），并对接 backend 的 OmniFocusConnector，模拟或实际执行 OmniFocus 的 AppleScript 调用。
  • 提供服务器入口点，直接通过 python -m omnifocus_mcp.server_fastmcp 启动，配合 MCP 客户端进行交互。

• 安装步骤

  • 克隆仓库并进入目录
  • 创建并激活虚拟环境（可选但推荐）
  • 安装依赖并安装当前项目
  • 启动服务器：python -m omnifocus_mcp.server_fastmcp
  • 运行环境要求：macOS（OmniFocus 为 macOS 专用）、OmniFocus 应用已安装并正在运行；如用于测试，请按仓库文档中的测试/集成方式配置测试数据库。

• 服务器配置（MCP 客户端需要的启动信息，以下为示例配置，JSON 表示法，后续客户端仅需要读取该配置来启动服务器，不需要直接修改服务器端代码）

  • server name: omnifocus
  • command: python
  • args: ["-m", "omnifocus_mcp.server_fastmcp"] 注释说明：
  • 该配置用于 Claude Desktop 或其他 MCP 客户端，指明服务器如何启动以及调用入口。客户端配置示例仅用于连接服务器端，实际服务器运行由本仓库提供的入口脚本完成。

• 基本使用方法

  • 启动服务器后，MCP 客户端（如 Claude Desktop、其他 LLM 助手的 MCP 客户端）即可通过 MCP 请求格式，与服务器进行交互。
  • 常用操作示例包括：查询项目/任务、创建/更新/删除任务与项目、查询文件夹、设置聚焦等，具体命令参数及返回格式遵循 MCP 的 JSON-RPC 约定。
  • 开发与调试时，可以在服务器端日志中查看 AppleScript 调用结果以及与 OmniFocus 的交互细节，帮助定位权限、路径或日期格式等问题。