FocusRelayMCP

Installation

Quick Overview: Regardless of which installation method you choose, you'll need to complete these steps: 1. Install the binary (via Homebrew, manual download, or build from source) 2. Install the OmniFocus plugin (Step 2 below) 3. Configure MCP in your client (Step 3 below) 4. Restart OmniFocus (Step 4 below)

Option A: Homebrew Installation (Recommended for macOS)

If you have Homebrew installed, this is the easiest method:

```bash

Install the MCP server and OmniFocus plugin

brew install focusrelay ```

Then continue with Step 2: Install the OmniFocus Plugin below.

Option B: Manual Binary Installation

If you don't want to use Homebrew, download a pre-built binary:

1. Download the latest release from the Releases page
2. Extract the binary to a location in your PATH (e.g., ~/bin/ or /usr/local/bin/)
3. Download the plugin: FocusRelayBridge.omnijs from the same release

Then continue with Step 2: Install the OmniFocus Plugin below.

Option C: Developer Installation (Build from Source)

Prerequisites

• macOS with OmniFocus installed (4.x recommended)
• Swift 6.2+ toolchain
• This has been tested on opencode but should work with Claude Desktop or other tools with MCP integration

Step 1: Clone and Build

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

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

Then continue with Step 2: Install the OmniFocus Plugin below.

Step 2: Install the OmniFocus Plugin

Homebrew users: Copy the plugin from the Homebrew installation:

cp -r $(brew --prefix focusrelay)/share/focusrelay/Plugin/FocusRelayBridge.omnijs \
  ~/Library/Containers/com.omnigroup.OmniFocus4/Data/Library/Application\ Support/Plug-Ins/

Developer installation:

./scripts/install-plugin.sh

This installs the FocusRelay Bridge plugin to your OmniFocus plugin directory.

⚠️ IMPORTANT: When upgrading, you must reinstall the plugin! The plugin JavaScript changes frequently and must stay in sync with the binary.

Step 5: First Time Setup (Security Approval)

⚠️ Critical: The first time you query OmniFocus, a security dialog will appear:

1. Ask your AI assistant: "What should I do today?" (or any OmniFocus query)
2. OmniFocus will show a security prompt: "Allow script to control OmniFocus?"
3. Click "Run Script" (not "Cancel")
4. If you don't see the prompt, check if OmniFocus is behind other windows

What happens if you don't approve: - You'll see "Bridge timed out" or "Plugin not responding" errors - The MCP server cannot communicate with OmniFocus - Queries will fail silently or with timeout errors

To fix approval issues: - In OmniFocus: Automation → Configure Plug-ins... - Find "FocusRelay Bridge" in the list - Check if it's enabled, or try removing and reinstalling it - Restart OmniFocus and try again

Quick Validation After Setup

After Step 5, verify the install path end to end:

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

Expected result: - bridge-health-check reports ok: true - the first list-tasks query may trigger the OmniFocus approval prompt - after approval, list-tasks returns real task data instead of timing out

Build

swift build

CLI Usage

The focusrelay binary provides command-line equivalents of the MCP tools. Run focusrelay --help for the full command list.

```bash

Usage Examples

Step 3: Configure MCP

Add to your opencode.json or Claude Desktop config:

For Homebrew installations (recommended):

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

For developer installations (build from source):

{
  "mcp": {
    "focusrelay": {
      "type": "local",
      "command": ["/path/to/FocusRelayMCP/.build/release/focusrelay", "serve"],
      "enabled": true
    }
  }
}

Note: focusrelay without arguments shows help; use focusrelay serve to run the MCP server.

"Bridge timed out" or "Plugin not responding"

This is the most common issue. Several causes:

1. Security approval missing (most common) - Solution: See Step 5 (First Time Setup) above. You must click "Run Script" in the OmniFocus security dialog.

2. Plugin needs reinstallation - Solution: Run ./scripts/install-plugin.sh again, then restart OmniFocus completely

3. OmniFocus not properly restarted after plugin update - Solution: Force quit OmniFocus and reopen it

4. Check plug-in configuration - In OmniFocus: Automation → Configure Plug-ins... - Verify "FocusRelay Bridge" appears in the list and is enabled - If you see errors here, remove the plug-in and reinstall

Package Plugin

./scripts/package-plugin.sh

Troubleshooting