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?

Keep the assistant focused

FocusRelay exposes nine model-facing tools: seven read tools plus edit_tasks and edit_projects for 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.

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:

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

Formula-specific trust authorizes FocusRelay without trusting every current or future formula in the tap. See Homebrew’s Tap Trust documentation for details.

2. Run guided setup

Run the installed setup command:

focusrelay setup

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 opencode for 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.

3. Restart OmniFocus

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

FocusRelay currently supports terminal-based MCP clients: Claude Code, OpenCode, Codex CLI, and other clients launched from a terminal. Desktop applications such as Claude Desktop and ChatGPT's desktop app are not yet supported: macOS restricts their access to the OmniFocus data FocusRelay relies on. Desktop-app support is tracked in #196.

Configure a local stdio MCP server with:

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

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

claude mcp list

{
  "mcp": {
    "focusrelay": {
      "type": "local",
      "command": ["/opt/homebrew/bin/focusrelay", "serve"],
      "enabled": true
    }
  }
}

On the first query, OmniFocus asks whether to allow the automation. Choose Run Script. If the prompt is hidden, bring OmniFocus to the front.

After restarting OmniFocus, verify that its loaded plug-in matches the binary:

focusrelay setup --check-readiness
focusrelay list-tasks --fields id,name --limit 1

Then ask:

How many flagged items do I have in OmniFocus?

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

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