使用说明

OmniFocus MCP服务器

基于Python的模型上下文协议（MCP）服务器，使Claude等AI助手能够在macOS上与OmniFocus进行交互。该服务器提供工具，通过人工智能助手使用自然语言在OmniFocus中读取、创建、编辑和删除任务和项目。

🤖 整个项目都是人工智能写的。是的，甚至这句话。AI为自己感到骄傲。

特性

🔧 全面的OmniFocus集成：添加、编辑、删除和查询任务和项目
📝 Markdown注释：任务/项目注释是Markdown——粗体、斜体、内联代码、链接、标题和列表在写入时转换为OmniFocus原生富文本，在读取时转换回Markdown，因此可以在不丢失格式或链接的情况下进行双向编辑
🐍 官方Python MCP SDK：使用官方MCP SDK构建
🔌 标准/标准运输：用于无缝集成的标准MCP stdio协议
⚡ 紫外线支持：全面支持UV包管理器，包括 uvx 用于快速安装
🚀 简易安装：使用一个命令直接从GitHub安装
🧩 模块化设计：将工具组织在单独的模块中，以提高可维护性

安装

uvx快速入门（推荐）

运行服务器而不安装：

uvx --from git+https://github.com/igrybkov/omnifocus-mcp omnifocus-mcp

使用UV

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install from GitHub
uv tool install git+https://github.com/igrybkov/omnifocus-mcp

# Run the server
omnifocus-mcp

使用pip

pip install git+https://github.com/igrybkov/omnifocus-mcp
omnifocus-mcp

开发安装

git clone https://github.com/igrybkov/omnifocus-mcp.git
cd omnifocus-mcp
uv sync
uv run omnifocus-mcp

对于本地开发，存储库包括 .mcp.json MCP客户端配置文件。

用法

使用克劳德桌面

配置Claude Desktop的最简单方法（只需要uv）：

uv tool run --from git+https://github.com/igrybkov/omnifocus-mcp omnifocus-cli add-server ~/Library/Application\ Support/Claude/claude_desktop_config.json

或者手动将其添加到配置文件中(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "omnifocus": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/igrybkov/omnifocus-mcp",
        "omnifocus-mcp"
      ]
    }
  }
}

或者，如果您安装了 uv tool install:

{
  "mcpServers": {
    "omnifocus": {
      "command": "omnifocus-mcp"
    }
  }
}

更新配置后，重新启动Claude Desktop。

可用工具

服务器提供了10个与OmniFocus交互的工具（加上一个勇敢的调试工具）：

任务工具

工具	它做什么
`add_omnifocus_task`	创建具有所有花哨功能的任务（日期、标志、标签、估计值、父任务）
`edit_item`	编辑任务或项目（重命名、日期、标志、标签、状态更改）
`remove_item`	按ID或名称删除任务或项目

项目工具

工具	它做什么
`add_project`	使用日期、标志、标签、文件夹位置、顺序设置创建项目
`browse`	通过筛选浏览文件夹/项目/任务层次结构

批量工具

工具	它做什么
`batch_add_items`	批量创建具有层次结构支持的任务/项目（当你有很多事情要做时）
`batch_remove_items`	批量删除任务/项目（当你做了很多事情时）

查询工具

工具	它做什么
`search`	按项目、标签、状态、日期等进行强大的筛选查询

透视工具

工具	它做什么
`list_perspectives`	列出内置和自定义透视图
`get_perspective_view`	从特定角度查看项目

工具配置

可以通过环境变量启用/禁用工具。默认情况下，所有工具都处于启用状态，除了 dump_database （因为AI代理喜欢在你最意想不到的时候转储整个数据库）。

格式: TOOL_<TOOL_NAME_UPPERCASE>=true|false

要启用调试工具，请执行以下操作：

{
  "mcpServers": {
    "omnifocus": {
      "command": "omnifocus-mcp",
      "env": {
        "TOOL_DUMP_DATABASE": "true"
      }
    }
  }
}

要禁用特定工具，请执行以下操作：

{
  "mcpServers": {
    "omnifocus": {
      "command": "omnifocus-mcp",
      "env": {
        "TOOL_BATCH_REMOVE_ITEMS": "false"
      }
    }
  }
}

调试工具

工具	它做什么
`dump_database`	导出整个OmniFocus数据库（默认情况下禁用，启用风险由您自行承担）

CLI接口

还有一个CLI用于测试工具和管理配置。运行而不安装：

# Shorthand for examples below
alias omnifocus-cli='uv tool run --from git+https://github.com/igrybkov/omnifocus-mcp omnifocus-cli'

# Add server to an MCP config file
omnifocus-cli add-server ~/Library/Application\ Support/Claude/claude_desktop_config.json

# List available tools
omnifocus-cli list-tools

# Run tools with named flags
omnifocus-cli add-omnifocus-task --name "Buy groceries" --project "Shopping" --flagged
omnifocus-cli search --entity tasks --filters '{"flagged": true}'

# Generic call with JSON arguments
omnifocus-cli call search '{"entity": "tasks", "filters": {"due_within": 3}}'

项目结构

src/omnifocus_mcp/
├── server.py                # Main server and tool registration
├── cli.py                   # CLI interface
├── utils.py                 # Utility functions (AppleScript escaping)
├── dates.py                 # Date parsing and AppleScript generation
├── tags.py                  # Tag modification AppleScript
├── omnijs.py                # OmniJS execution via JXA
├── applescript_builder.py   # High-level AppleScript builders
├── scripts/                 # OmniJS scripts
│   └── common/              # Shared JS modules
└── mcp_tools/
    ├── tasks/               # add_task, edit_item, remove_item
    ├── projects/            # add_project, browse
    ├── batch/               # batch_add, batch_remove
    ├── query/               # search
    ├── perspectives/        # list_perspectives, get_perspective_view
    └── debug/               # dump_database

发展

运行测试

该项目包括一个使用pytest的全面测试套件：

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_tasks.py

# Run with coverage
pytest --cov=omnifocus_mcp

需求

macOS（OmniFocus仅适用于macOS）
OmniFocus已安装并正在运行
Python 3.10或更高版本

运作原理

此MCP服务器使用AppleScript进行CRUD操作，使用OmniJS（通过JXA）进行查询。当您通过Claude或其他MCP客户端发出请求时：

客户端通过stdin发送请求
MCP服务器处理请求
执行AppleScript/OmniJS命令以与OmniFocus交互
结果通过stdout返回给客户端

所有用户输入都被正确转义，以防止AppleScript注入攻击。

动机与设计哲学

这个项目的灵感来自运动机/OmniFocus MCP，但创建是为了解决特定的限制：

关键改进

高效的数据库访问：The dump_database 默认情况下，该工具是隐藏的，以防止AI代理不必要地转储整个数据库。这对于拥有大型OmniFocus数据库的用户来说至关重要，因为频繁的转储会成为性能瓶颈。
快速功能采用：独立开发允许快速实施新的OmniFocus功能（如计划日期），而无需等待上游项目维护人员。
模块化架构：工具被组织在单独的模块中，以实现更好的可维护性和更容易的扩展。

技术栈

python：使用现代工具获得更便捷的开发体验
官方MCP SDK：使用官方Python MCP SDK构建
UV包装管理器：现代Python包管理，安装简单 uvx

贡献

欢迎投稿！请随时提交拉取请求。AI承诺不会嫉妒。

许可证

MIT许可证-您可以在自己的项目中自由使用！