OmniFocus MCP Server

OmniFocus MCP Server

A comprehensive, fast, reliable, and agent-friendly MCP server for OmniFocus on macOS.

Why This Server

Comprehensive

21 tools covering projects, tasks, folders, tags, perspectives, and focus. Full CRUD with unified batch operations (Pydantic model inputs), 20+ filter types on task and project queries, and date management including recurrence (RRULE read/write).

Fast

Sub-second reads on filtered queries, even with hundreds of tasks in the database.

Full profiling data: PERFORMANCE_PROFILING.md

Reliable

93% code coverage from 1027 unit tests. 192 integration and E2E tests run against real OmniFocus, plus 5 protocol-level smoke tests verifying the full MCP JSON-RPC transport. Tests cover task, project, and tag lifecycles, filtering, hierarchy, dates, recurrence, and review workflows.

Agent-Friendly

73-scenario blind eval suite with frontier models scoring 100% and popular open-weight models scoring 90-94% (full results). Agents that have never seen OmniFocus can correctly use every tool from descriptions alone. Scenarios cover tool selection, parameter usage, multi-step workflows, date semantics, recurrence, tag behavior, task movement, text search, and safety-critical operations (drop vs delete, destructive action guardrails). Server instructions teach GTD concepts (task states, project types, sequential dependencies, review cycles) so agents make informed decisions, not just API calls.

Tools (21)

Projects (6)

• get_projects — filter by ID, query, status; includes dates, review info, task health, stalled detection
• create_project — with folder placement, dates, review interval, project type
• update_project — all properties: name, note, status, dates, folder, review settings
• update_projects — batch update (status, dates, folder, review settings)
• delete_projects — single or batch
• reorder_project — position relative to siblings within a folder (before/after)

Tasks (6)

• get_tasks — 14 filter types: by ID, project, parent, tags, status, dates, flags, text search, inbox
• create_task — with dates, tags, flags, estimated time, parent task, sequential
• update_task — all properties including recurrence (RRULE), tags (replace/add/remove), hierarchy
• update_tasks — batch update (dates, flags, tags, status, project)
• delete_tasks — single or batch
• reorder_task — position relative to siblings (before/after)

Folders (3)

• get_folders — hierarchy with paths
• create_folder — with optional parent
• update_folder — rename or move to different parent

Tags (4)

• get_tags — with status and mutual exclusivity info
• create_tag — with parent nesting and exclusivity
• update_tag — name, status, exclusivity
• delete_tags — single or batch

Perspectives (2)

• get_perspectives — list with type info
• switch_perspective — navigate to perspective

Navigation (2)

• set_focus — focus on projects/folders or clear
• get_focus — current focus state

Prerequisites

• macOS with OmniFocus installed
• Python 3.10+
• uv package manager

Installation

git clone https://github.com/s-morgan-jeffries/omnifocus-mcp.git
cd omnifocus-mcp
git checkout v0.13.2  # Latest stable release

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --dev

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/omnifocus-mcp",
        "run",
        "omnifocus-mcp"
      ]
    }
  }
}

Other MCP Clients

python -m omnifocus_mcp.server_fastmcp

Communicates via stdin/stdout using the MCP protocol.

Permissions

macOS will prompt for:

• Accessibility access (to control OmniFocus via AppleScript)
• Automation permissions for OmniFocus

Contributing

Bug reports and feature requests are welcome via GitHub Issues.

License

MIT