🎯 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.

⚠️ Claude Desktop on recent macOS — temporary extra step. macOS may block the server from reading OmniFocus's data. From v1.4.6 the server stays up and every tool call tells you exactly what to do, including the path to add. In short:

1. If macOS asks whether uvx may access data from other apps, click Allow (it asks again on each launch).

2. To stop being asked, or if no prompt appears: open System Settings → Privacy & Security → Full Disk Access, click +, press ⌘⇧G, and add the real uvx binary. The server's error message names its exact path.

3. Quit Claude Desktop completely (⌘Q) and reopen it.

Granting Full Disk Access to Claude itself does not help — Claude Desktop launches MCP servers as their own responsible process. The grant applies to everything you run through uvx, not only OmniFocus Operator. Terminal clients such as Claude Code are not affected. A proper installer that removes this step is planned.

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

See CONTRIBUTING.md for dev workflow details.

Related MCP server: OmniFocus MCP Server

✨ 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.