FocusRelay — Fast Swift OmniFocus MCP Server and CLI for macOS

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 assistantsread 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 approvedchanges without clicking through long task lists.

Ask. Review. Update.

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

Try prompts like:

• “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 thechange.”

These workflows were tested against the released Homebrew build with Kimi K2.7Code, and the inbox query with a second MCP-capable model. Updates target stableOmniFocus IDs and can verify the saved result. If names are duplicated, ask tosee the candidates before changing anything.

FocusRelay 0.10.0-beta can:

• find and count tasks using dates, flags, tags, projects, availability, inboxstate, completion, estimates, and text search;
• review projects, folders, tags, task counts, and stalled work;
• update names, notes, flags, dates, estimates, tags, project settings, andreview intervals;
• complete, reactivate, change status, and move existing tasks and projects;
• preview a proposed change and verify the saved result.

The current beta updates existing tasks and projects. Creating or deletingitems is not part of this release; creation is tracked in#82 and#83.

Why FocusRelay?

Keep the assistant focused

FocusRelay exposes 14 model-facing tools—seven for reading and seven for makingsupported changes. Internal diagnostics stay in the CLI, count commands avoidreturning 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 noNode.js or Python runtime in the request path. Single-pass filtering andearly-stop pagination keep focused inbox reads near one second in testing atthousands-of-tasks scale. The same core powers a CLI for precise, low-contextqueries.

Run where OmniFocus understands its data

The Swift server dispatches work to a lightweight bridge plug-in that runsinside OmniFocus’s Omni Automation context. It uses documented APIs and nativestatuses, keeping results aligned with OmniFocus without reading its privatedatabase.

Make changes you can check

Update tools target stable IDs and support previews, per-item results, compactreturn fields, and optional verification. A failed save, update, or verificationis reported as a failure—not success.

Validation covered thousands of tasks and thousands of measured calls withouterrors or timeouts in the final benchmark runs. See the0.10.0-beta release notes for evidence andlimits.

Privacy and security

FocusRelay runs locally on your Mac. Its Swift server communicates on-devicewith a bridge plug-in that accesses OmniFocus through documented APIs.FocusRelay has no hosted cloud service and does not send your OmniFocus data toa FocusRelay-operated service.

Your MCP client and chosen AI model may transmit tool inputs and results undertheir own privacy terms. Review those settings before using FocusRelay withsensitive data.

Install the OmniFocus MCP server with Homebrew

Requirements:

• macOS 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. Trustonly 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 orfuture formula in the tap. See Homebrew’sTap Trust documentation for details.

2. Install the OmniFocus plugin

mkdir -p "$HOME/Library/Containers/com.omnigroup.OmniFocus4/Data/Library/Application Support/Plug-Ins"
cp -R "$(brew --prefix focusrelay)/share/focusrelay/Plugin/FocusRelayBridge.omnijs" \
  "$HOME/Library/Containers/com.omnigroup.OmniFocus4/Data/Library/Application Support/Plug-Ins/"

The plugin and binary must stay on the same version. Repeat this copy step afterupgrading FocusRelay.

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. Add FocusRelay to your AI assistant

Configure a local stdio MCP server with:

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

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

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

5. Check the connection

focusrelay --version
focusrelay bridge-health-check
focusrelay list-tasks --fields id,name --limit 1

Then ask:

How many flagged items do I have in OmniFocus?

Download the latest binary and FocusRelayBridge.omnijs fromGitHub Releases, or buildwith the Swift 6.3.3 toolchain selected by the checked-in .swift-version:

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.

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 shellaccess.

# 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 update-tasks <task-id> \
  --flagged true \
  --preview-only \
  --return-fields id,name,flagged

Run focusrelay --help for the command list. For write examples and safetyrules, see Safe Update Workflows for CLI and MCP.

Compare FocusRelay with other OmniFocus MCP servers

FocusRelay combines a native Swift server with a bridge plug-in that executesinside OmniFocus. Swift keeps MCP fast and compact; the bridge gets fresh dataand 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 publicREADMEs do not describe an equivalent per-target preview and post-saveverification contract.

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

Help shape FocusRelay

See GitHub Issues for plannedwork. If FocusRelay earns a place in your workflow,star the repository so moreOmniFocus users can find it.

Want to help? Pick an issue, propose a use case, or open a focused pull request.See CONTRIBUTING.md to get started.

Troubleshooting

The bridge times out

1. Bring OmniFocus to the front and accept the first Run Script prompt.
2. Confirm FocusRelay Bridge is enabled under Automation → ConfigurePlug-ins….
3. Recopy the plugin, quit OmniFocus completely, and reopen it.
4. Run focusrelay bridge-health-check.

Results look stale after an upgrade

The plugin JavaScript is cached by OmniFocus. Reinstall the plugin and restartOmniFocus completely. Project and tag catalogs cache for five minutes; taskqueries are always fresh.

A time-based result looks wrong after travel

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

Development

swift build
swift test

FocusRelay uses Swift Testing from the Swift toolchain. Production query changesmust follow the documentedOmni Automation contract.

License

FocusRelay is available under the MIT License.