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

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/first-run-dark.png"> <img src="docs/images/first-run-light.png" alt="OmniFocus first-run permission dialog showing OmniFocus Operator's welcome banner with two steps: tick the 'Automatically run' checkbox, then click Run Script" width="600"> </picture>

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.

<details> <summary><strong>Development install (contributors)</strong></summary>

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

See CONTRIBUTING.md for dev workflow details.

</details>

---

✨ 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

Tool	Description
get_all	Full OmniFocus database as structured data (last-resort debugging)
get_task	Single task by ID — urgency, availability, dates, tags, parent, project
get_project	Single project by ID — status, review interval, next task
get_tag	Single tag by ID — availability, parent hierarchy

List & Filter

Tool	Description
list_tasks	Filter by date, availability, flags, tags, project, parent subtree, search — with pagination, field selection, and presence-flag derivation
list_projects	Filter by status, folder, review schedule, flags
list_tags	List tags with parent hierarchy
list_folders	List folders with parent hierarchy
list_perspectives	List custom perspectives

Write

Tool	Description
add_tasks	Create tasks with full field control — parent, tags, dates, flags, notes, repetition rules, parallel/sequential, completes-with-children
edit_tasks	Patch semantics — update fields, move tasks, complete/drop, manage tags, repetition rules, and hierarchy properties

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:

Input	Meaning
Field omitted	No change
Field set to null	Clear the value
Field set to a value	Update

---

🗺️ Roadmap

Version	Focus
v1.0	Foundation — read tools, three-layer arch, test suite ✅
v1.1	Performance — SQLite caching, 30–60x speedup ✅
v1.2	Writes & Lookups — add/edit tasks, get-by-ID ✅
v1.2.1	Architectural Cleanup — contracts, service refactor, golden master tests ✅
v1.2.2	FastMCP v3 Migration ✅
v1.2.3	Repetition Rule Write Support ✅
v1.3	Read Tools — SQL filtering, list/count, 5 new tools ✅
v1.3.1	First-Class References — name resolution, $inbox, rich refs ✅
v1.3.2	Date Filtering — 7 dimensions, shortcuts, calendar math ✅
v1.3.3	Task Ordering — dotted notation, outline order ✅
v1.4	Response Shaping & Batch Processing ✅
v1.4.1	Task Properties & Subtree — presence flags, auto-complete, parallel/sequential, parent filter ✅
v1.4.2	UNTIL Format Hotfix — parser accepts RFC 5545 DATE form; builder aligns with OmniFocus UI ✅
v1.4.3	First-Run UX — welcome banners in bridge.js that frame OmniFocus's permission dialog with two-click instructions; startup log line ✅
v1.5	Project Writes — add/edit projects, review marking
v1.6	UI & Perspectives — perspective switching, deep links
v1.7	Smart Perspective Content — perspective-aware response shapes
v1.8	Production Hardening — retry, crash recovery, serial execution

---

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