🎯 OmniFocus Operator

The last OmniFocus MCP Server you'll ever need.

Production-grade MCP server exposing OmniFocus as structured task infrastructure for AI agents. Agent-first design, SQLite-cached performance, 2,561 tests.

→ See the full landing page — features, architecture, benchmarks, and comparison

🚀 Quick Start

Prerequisites: macOS, OmniFocus 4, Python 3.12+

🪄 Not sure where this config goes? The setup wizard on the landing page walks you through it step-by-step — including auto-merging with your existing config.

For Claude Desktop

Paste this into ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omnifocus-operator": {
      "command": "uvx",
      "args": ["omnifocus-operator"]
    }
  }
}

uvx downloads, isolates, and runs the server automatically. No install step.

First run: OmniFocus shows a one-time permission dialog. Tick the box, click Run Script. You won't see it again.

For Claude Code, OpenCode, Cursor…

Ask your agent — copy this prompt:

Add this MCP server to my client config. Just edit the config file — don't install anything, don't run any scripts.

"omnifocus-operator": {
  "command": "uvx",
  "args": ["omnifocus-operator"]
}

⚠️ This doesn't work with Claude Desktop — Desktop has no config-editing tools. Use the manual paste above.

git clone https://github.com/HelloThisIsFlo/omnifocus-operator.git
cd omnifocus-operator
uv sync

✨ Features

• ⚡ 46ms reads — SQLite caching gives 30–60x faster reads than bridge-only servers
• 🛠️ 11 MCP tools — lookups, filtered lists, task creation & editing
• 🤖 Agent-first design — warnings that teach, errors that educate, guidance in every response
• 🧪 2,561 tests, 97% coverage — strict mypy, no corners cut
• 🛡️ Graceful degradation — server stays alive no matter what, always recoverable
• 🔄 Automatic fallback — SQLite → OmniJS bridge when needed

See the full documentation for architecture details, examples, and deep dives.

🛠️ Available Tools

Lookups

List & Filter

Write

All read tools are idempotent. Write tools reference projects and tags by name or ID.

🔍 Tool Examples

Filter tasks (list_tasks):

{
  "query": {
    "flagged": true,
    "due": "soon",
    "availability": "remaining",
    "include": ["notes"],
    "limit": 10
  }
}

Create a task (add_tasks):

{
  "items": [{
    "name": "Review Q3 roadmap",
    "parent": "Work Projects",
    "tags": ["Planning"],
    "dueDate": "2026-03-15T17:00:00",
    "flagged": true,
    "estimatedMinutes": 30,
    "note": "Focus on v1.3-v1.5 milestones"
  }]
}

Edit with patch semantics (edit_tasks):

{
  "items": [{
    "id": "oRx3bL_UYq7",
    "dueDate": null,
    "actions": {
      "tags": {"add": ["Urgent"]},
      "move": {"ending": "Work Projects"}
    }
  }]
}

Patch semantics cheat sheet:

🗺️ Roadmap

🔗 Links

• 📖 Full Documentation — features, architecture, examples
• 📦 PyPI — package page
• 🐛 Issues
• 💬 Discussions

📄 License

Proprietary — all rights reserved. Free to use, not to redistribute. License under review.

🤝 Contributing

See CONTRIBUTING.md for guidelines. In short: fork, branch, test, PR.