FocusRelayMCP

FocusRelayMCP exposes a natural-language interface to query and manipulate your OmniFocus data from AI assistants. The server runs locally and bridges between your AI prompts and OmniFocus, enabling tasks, projects, and tag-based queries to be expressed in everyday language. Typical use cases include daily planning (e.g., asking what you should be doing today or this afternoon), project health checks (identifying stalled projects or missing next actions), context switching (filtering by available contexts or devices), and task discovery (finding procrastinated or deferred tasks). The CLI tools exposed by the FocusRelay binary mirror MCP capabilities, allowing precise operations like listing tasks, listing projects with counts, fetching a specific task, and performing bridge-health checks. By supporting time-based, completion-date filtering, and smart tagging, FocusRelayMCP aims to deliver fast, single-pass filtering with local processing and timezone awareness.

Prerequisites:

• macOS with OmniFocus installed
• Swift 6.2+ toolchain
• Git
• Basic familiarity with the command line

Step 1: Clone the repository and build

git clone <repository-url>
cd FocusRelayMCP
swift build -c release

The compiled binary will be at .build/release/focusrelay (CLI + MCP server).

Step 2: Install the OmniFocus plugin (as described in the README)

• If using Homebrew: follow the Homebrew installation steps from the README to install the plugin and then install the CLI bridge as needed.
• If building from source, run the provided install-plugin script after configuring the MCP server.

Step 3: Run the MCP server locally

/path/to/FocusRelayMCP/.build/release/focusrelay serve

This starts the MCP server so your MCP client can connect and issue queries via natural language or the provided CLI tools.

Tips and considerations:

• The first run requires OmniFocus automation approval. If you see a security prompt, click Run Script to grant permission.
• Ensure the FocusRelay bridge plugin is kept in sync with the binary after upgrades.
• For macOS updates or OmniFocus plugin changes, you may need to restart OmniFocus to establish the bridge again.
• When configuring the MCP in your opencode.json or Claude Desktop config, Point the server to the local binary with serve as the argument, as shown in the README example.
• Dates in queries should use ISO8601 format. The server supports timezone-aware filtering, so queries will respect your local time zone.
• If you encounter bridge-timeouts, check plugin status in OmniFocus under Automation → Configure Plug-ins and re-run the plugin installer if necessary.