FocusRelay — Fast Swift OmniFocus MCP Server and CLI for macOS
Plan your day and keep OmniFocus up to date with AI
FocusRelay is a fast, native Swift MCP server and CLI that helps AI assistants
read and safely update OmniFocus using documented OmniFocus APIs.
Install with Homebrew ·
See what it can do ·
Star FocusRelay ·
Contribute
Ask about the work already in OmniFocus, review the answer, and make approved
changes without clicking through long task lists.
Ask. Review. Update.
FocusRelay is designed for targeted questions and compact answers, so the
assistant does not need your entire OmniFocus database for routine requests.
Try prompts like:
- “Help me process my OmniFocus inbox in a small batch.”
- “How many flagged items do I have?”
- “Show me the first three available tasks in my inbox.”
- “Find my task called [task name], flag it, and verify the change.”
- “Set [task name] due tomorrow at 5 PM in my local timezone and verify the
change.”
In clients that expose MCP server prompts, select process_inbox. In OpenCode,
run /focusrelay:process_inbox to start the guided workflow.
CLI-based agents can retrieve the exact same instructions with
focusrelay workflow get process_inbox; use focusrelay workflow list to
discover available workflows without loading their full text.
These workflows were tested with multiple MCP-capable models in OpenCode.
Updates target stable OmniFocus IDs and can verify the saved result. If names
are duplicated, ask to see the candidates before changing anything.
The current release can:
- guide supported MCP clients and CLI-based agents through a bounded,
approval-first inbox workflow;
- find and count tasks using dates, flags, tags, projects, availability, inbox
state, completion, estimates, and text search;
- review projects, folders, tags, task counts, and stalled work;
- update names, notes, flags, dates, estimates, tags, project settings, and
review intervals;
- mark active and on-hold projects reviewed using OmniFocus's native review
timestamp and next-review semantics;
- drop, restore, complete, reactivate, and move existing tasks;
- complete, reactivate, change status, and move existing projects;
- preview a proposed change and verify the saved result.
The current release updates existing tasks and projects. Creating or
deleting items is not supported; creation is tracked in
#82 and
#83.
Why FocusRelay?
On the development branch, Forecast questions support an explicit
partial task-only scope. It includes past/today
scheduled actions, flags, and the configured Forecast tag; it is not the native
Forecast total and excludes calendar events and native visibility preferences.
This requires the matching development binary and bridge, not the current
Homebrew release.
Keep the assistant focused
The development candidate exposes ten model-facing tools: seven read tools plus edit_tasks,
edit_projects, and add_tasks for supported changes. Task and subtask creation
uses client-managed approval, optional preview, frozen date-only values, and
mandatory verification. Omitted previewOnly performs a write; uncertain
creation must not be automatically retried. See the
creation contract.
Earlier consolidation from seven editing tools to two reduced the catalog
from 14 tools to 9 and cut context usage by 7–13% in controlled model tests.
Those historical measurements do not measure the new creation tool's overhead.
Internal diagnostics stay in the CLI, count commands avoid returning long item
lists, and field selection keeps responses compact.
Native Swift speed at real-library scale
FocusRelay is compiled as native Swift and installed with Homebrew, with no
Node.js or Python runtime in the request path. Single-pass filtering and
early-stop pagination keep focused inbox reads near one second in testing at
thousands-of-tasks scale. The same core powers a CLI for precise, low-context
queries.
Run where OmniFocus understands its data
The Swift server dispatches work to a lightweight bridge plug-in that runs
inside OmniFocus’s Omni Automation context. It uses documented APIs and native
statuses, keeping results aligned with OmniFocus without reading its private
database.
Make changes you can check
Edit tools target stable IDs and support previews, per-item results, compact
return fields, and optional verification. A failed save, update, or verification
is reported as a failure—not success.
FocusRelay handles OmniFocus work in order, tells assistants to wait for each
update, and reports overload clearly instead of letting requests collide.
When an MCP client disconnects, its FocusRelay process exits cleanly rather
than remaining in the background.
See the latest release notes for the
user-facing changes and upgrade requirements.
Privacy and security
FocusRelay runs locally on your Mac. Its Swift server communicates on-device
with a bridge plug-in that accesses OmniFocus through documented APIs.
FocusRelay has no hosted cloud service and does not send your OmniFocus data to
a FocusRelay-operated service.
Your MCP client and chosen AI model may transmit tool inputs and results under
their own privacy terms. Review those settings before using FocusRelay with
sensitive data.
Install the OmniFocus MCP server with Homebrew
Requirements:
- macOS 26 or later on Apple silicon;
- OmniFocus 4;
- Homebrew;
- an MCP-compatible assistant or a shell-capable AI agent.
1. Install and trust the formula
Homebrew 6 requires explicit trust for formulae from non-official taps. Trust
only the FocusRelay formula, then install it:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
