OmniFocus Operator
README.md
# π― OmniFocus Operator
**The last OmniFocus MCP Server you'll ever need.**

[](https://pypi.org/project/omnifocus-operator/)



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**](https://hellothisisflo.github.io/omnifocus-operator) β features, architecture, benchmarks, and comparison
---
## π Quick Start
**Prerequisites:** macOS, OmniFocus 4, Python 3.12+
> πͺ **Not sure where this config goes?** The [setup wizard](https://hellothisisflo.github.io/omnifocus-operator) 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`:
```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>
> β οΈ **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.
>
> ```json
> "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>
```bash
git clone https://github.com/HelloThisIsFlo/omnifocus-operator.git
cd omnifocus-operator
uv sync
```
See [CONTRIBUTING.md](https://github.com/HelloThisIsFlo/omnifocus-operator/blob/main/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](https://hellothisisflo.github.io/omnifocus-operator) 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`):
```json
{
"query": {
"flagged": true,
"due": "soon",
"availability": "remaining",
"include": ["notes"],
"limit": 10
}
}
```
**Create a task** (`add_tasks`):
```json
{
"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`):
```json
{
"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](https://hellothisisflo.github.io/omnifocus-operator) β features, architecture, examples
- π¦ [PyPI](https://pypi.org/project/omnifocus-operator/) β package page
- π [Issues](https://github.com/HelloThisIsFlo/omnifocus-operator/issues)
- π¬ [Discussions](https://github.com/HelloThisIsFlo/omnifocus-operator/discussions)
---
## π License
Proprietary β all rights reserved. Free to use, not to redistribute. License under review.
## π€ Contributing
See [CONTRIBUTING.md](https://github.com/HelloThisIsFlo/omnifocus-operator/blob/main/CONTRIBUTING.md) for guidelines. In short: fork, branch, test, PR.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues