OmniFocus Operator MCP server
Commit Nov 13, 2026Exposes OmniFocus tasks, projects, and tags to AI agents for structured task management and automation.
Also known as HelloThisIsFlo/omnifocus-operator
- Stars
- 11
- Tools
- 11
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- —
What is OmniFocus Operator MCP?
OmniFocus Operator exposes OmniFocus tasks, projects, and tags to AI agents for structured task management and automation. It exposes 11 tools, such as get_all, get_task, get_project.
Summary generated from the project's README
About OmniFocus Operator MCP server
Managing complex task lists and project hierarchies through AI agents is what this server enables for macOS users. It connects OmniFocus 4 to MCP clients like Claude Desktop, Claude Code, or Cursor, allowing an agent to interact directly with your personal productivity data. By using uvx to run the server, you can quickly integrate your existing task infrastructure without a manual installation process.
The server provides 11 specialized tools for looking up specific tasks, projects, or tags, and for filtering large lists by dates, flags, or availability. It supports writing operations, meaning an agent can create new tasks with full field control or edit existing ones using patch semantics to update notes, move items between projects, or manage repetition rules.
Performance is a core focus, utilizing SQLite caching to achieve 46ms reads, which is significantly faster than standard bridge-only implementations. The system is designed for reliability, featuring automatic fallback to the OmniJS bridge and graceful degradation to ensure the server remains recoverable during use.
Written from the project's README. Every use case is checked against a quote from it.
OmniFocus Operator MCP tools 11
Detected from the READMEget_allget_taskget_projectget_taglist_taskslist_projectslist_tagslist_folderslist_perspectivesadd_tasksedit_tasks
| get_all | — | |
| get_task | — | |
| get_project | — | |
| get_tag | — | |
| list_tasks | — | |
| list_projects | — | |
| list_tags | — | |
| list_folders | — | |
| list_perspectives | — | |
| add_tasks | — | |
| edit_tasks | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehellothisisflo/omnifocus-operator is public and reachablegithub.com/hellothisisflo/omnifocus-operator ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-12github.com/hellothisisflo/omnifocus-operator ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model11 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub🎯 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:
- If macOS asks whether
uvxmay access data from other apps, click Allow (it asks again on each launch).- To stop being asked, or if no prompt appears: open System Settings → Privacy & Security → Full Disk Access, click +, press ⌘⇧G, and add the real
uvxbinary. The server's error message names its exact path.- 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.
✨ 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.4.4 | Batch Limit Increase — add_tasks / edit_tasks accept up to 150 items per call ✅ |
| v1.4.5 | FastMCP Version Cap — dependency capped below 3.4 to restore agent-facing validation errors ✅ |
| v1.4.6 | Startup Access Errors — macOS privacy blocks no longer crash the server; tool calls explain the fix ✅ |
| v1.4.7 | FastMCP 4 — runs on FastMCP 4; agent-facing validation errors restored on current FastMCP ✅ |
| 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.
OmniFocus Operator MCP questions
What tools does OmniFocus Operator MCP provide?
It exposes 11 tools, including get_all, get_task, get_project, get_tag, list_tasks.
What are the system requirements for OmniFocus Operator?
You need a macOS system, OmniFocus 4, and Python 3.12 or higher.
How do I fix macOS privacy blocks when using Claude Desktop?
You may need to grant Full Disk Access to the uvx binary in System Settings → Privacy & Security.
Can the server handle large batches of tasks?
Yes, the add_tasks and edit_tasks tools can accept up to 150 items per call.
Is there a way to run this without a manual installation step?
Yes, using uvx allows you to download, isolate, and run the server automatically.