FocusRelay

Ask about the work already in OmniFocus, review the answer, and make approved changes without clicking through long task lists.

FocusRelay is designed for targeted questions and compact answers, so the assistant does not need your entire OmniFocus database for routine requests.

FocusRelay exposes nine model-facing tools: seven read tools plusedit_tasksandedit_projectsfor supported changes. Combining seven editing tools into two reduced the full catalog from 14 tools to 9 and cut context usage by 7–13% in controlled model tests, leaving more room for the user's actual work. 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.

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.

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

- macOS 26 or later on Apple silicon;
- OmniFocus 4;
- Homebrew;
- an MCP-compatible assistant or a shell-capable AI agent.

Homebrew 6 requires explicit trust for formulae from non-official taps. Trust only the FocusRelay formula, then install it:

brew tap deverman/focus-relay brew trust --formula deverman/focus-relay/focusrelay brew install focusrelay

It finds the Homebrew-bundled plug-in, verifies that its version matches the binary, detects every supported OmniFocus plug-in folder, and previews the source and destinations before asking permission to copy anything. Existing plug-ins remain in place until their replacement has been copied successfully. Rerunning setup reports copies that are already current.

Setup also prints the client-neutral MCP command and arguments. Add--client claude-code,--client codex, or--client opencodefor a known client example; FocusRelay prints the configuration but does not edit it.

For automation, review the same plan first and then opt in explicitly:

focusrelay setup --dry-run focusrelay setup --non-interactive

Building from source? Continue using./scripts/install-plugin.sh; it is a thin development entry point for this same Swift setup implementation.

Quit OmniFocus completely and reopen it so the updated plugin is loaded:

osascript -e 'tell application "OmniFocus" to quit' sleep 2 open -a "OmniFocus"

4. Check readiness and add FocusRelay to your AI assistant

Configure a local stdio MCP server with:

- command:/opt/homebrew/bin/focusrelay
- arguments:serve

Claude Code registers MCP servers from the command line, so no file editing is required:

claude mcp add --scope user focusrelay -- /opt/homebrew/bin/focusrelay serve

--scope usermakes FocusRelay available in every project on your Mac. Use--scope projectinstead to share the server with collaborators through a checked-in.mcp.json, or omit the flag to enable it only in the current directory.

Confirm the server is registered and reachable:

FocusRelay should report✔ Connected. Remove it later withclaude mcp remove --scope user focusrelay.

git clone https://github.com/deverman/FocusRelayMCP.git cd FocusRelayMCP swift build -c release ./scripts/install-plugin.sh

After installing the plugin, restart OmniFocus completely and runfocusrelay setup --check-readiness.

Use FocusRelay as an OmniFocus MCP server or CLI

MCP lets compatible assistants discover FocusRelay and choose the right action. The CLI is useful for scripts, debugging, and agents that already have shell access.

The examples below target the current Homebrew release and source build.

# Discover or retrieve the same workflows exposed as MCP prompts focusrelay workflow list focusrelay workflow get process_inbox # Count without returning every matching task focusrelay task-counts --flagged true # Return only three task names focusrelay list-tasks \ --inbox-only true \ --available-only true \ --limit 3 \ --fields name # Preview a change without touching OmniFocus focusrelay edit-tasks <task-id> \ --operation update \ --flagged true \ --preview-only \ --return-fields id,name,flagged

Compare FocusRelay with other OmniFocus MCP servers

FocusRelay combines a native Swift server with a bridge plug-in that executes inside OmniFocus. Swift keeps MCP fast and compact; the bridge gets fresh data and applies changes through documented OmniFocus APIs.

✅ Available · 🟡 Coming next · 🟠 Backlog · ◇ Project roadmap · — Not currently documented

This comparison reflects each project’s public documentation on July 15, 2026; “Not documented” is not a claim that a feature is impossible. The other public READMEs do not describe an equivalent per-target preview and post-save verification contract.

Preview resolves IDs and validates the change without saving it. Verification runs after OmniFocus saves, reads the affected values back, and reports a mismatch as a failure. These are MCP tool arguments, so Codex, Claude Code, OpenCode, and other standard stdio MCP clients can use them; whether a model chooses them without being asked depends on the model and client. For important changes, ask it to “preview first, then apply with verification.”

The plugin JavaScript is cached by OmniFocus. Runfocusrelay setup, restart OmniFocus completely, and check withfocusrelay setup --check-readiness. Project and tag catalogs cache for five minutes; task queries are always fresh.

The plugin and binary versions do not match

Upgrading the Homebrew formula replaces the binary but leaves the copies of the plugin already installed for OmniFocus untouched, so a skipped step 2 can strand the plugin many releases behind.

Run guided setup again, restart OmniFocus, and check the loaded version:

focusrelay setup # Fully restart OmniFocus focusrelay setup --check-readiness

Setup checks that every expected copy—including the preferred iCloud location when plug-in sync is enabled—is available before changing files, and preserves each existing copy until its replacement has been copied and verified. It updates destinations one at a time, so if a later destination fails, an earlier one may already have been updated. Correct the reported problem and rerun setup before restarting OmniFocus. A healthy readiness result means the loaded plug-in, every installed copy, and the binary agree.

A time-based result looks wrong after travel

Restart the MCP client and OmniFocus so FocusRelay picks up the current macOS timezone.

Enables LLM clients to interact with macOS applications through AppleScript. Built using the @beyondbetter/bb-mcp-server library, this server provides safe, controlled execution of predefined scripts with optional support for arbitrary script execution.

On-device tools to detect AI-generated text and images, score readability, and strip AI artifacts, running locally on Apple silicon.

Interact with Apple Notes using natural language on macOS.

Free local MCP server for Apple Mail, Calendar, and Reminders on macOS.

A server for native integration with Apple Reminders on macOS.