FocusRelay

io.github.deverman由 GitHub 帳號 deverman 發布v0.10.0-beta更新於 Oct 24, 2026

Connect AI tools to OmniFocus on macOS to find, review, and safely update tasks and projects.

已驗證STDIO僅桌面效率與工作流檔案與儲存

概覽

AI 產生的概覽

本機 macOS MCP 伺服器與命令列工具,讓 AI 助理查詢、檢視並安全更新 OmniFocus 中的任務與專案。

可以做什麼
  • 依日期、旗標、標籤、專案、可用性、收件匣狀態、完成情況、預估與文字搜尋找出並統計任務
  • 檢視專案、檔案夾、標籤、任務數量以及停滯的工作
  • 更新名稱、備註、旗標、日期、預估、標籤、專案設定與檢閱間隔
  • 將專案標記為已檢閱,並擱置、還原、完成、重新啟用或移動現有任務與專案
  • 預覽擬議的變更並核對儲存後的結果
  • 執行引導式工作流程,例如有範圍限制、先核准的收件匣處理提示
適用情境
適合在 Mac 上用 OmniFocus 管理工作的人,讓助理回答關於任務的針對性問題、小批量處理收件匣,或在不必逐一點開長長任務清單的情況下完成已核准的修改。
執行需求
需要 Apple 晶片上的 macOS 26 或更新版本、OmniFocus 4、Homebrew,以及終端機形式的 MCP 用戶端(如 Claude Code、OpenCode 或 Codex CLI)。以 Homebrew 安裝,執行 setup 指令複製 OmniFocus 橋接外掛,重新啟動 OmniFocus,並在首次執行時核准 Run Script 自動化提示。目前不支援 Claude Desktop 等桌面應用程式。
安裝前請注意
此伺服器會變更你的 OmniFocus 資料:可更新、完成、擱置、還原與移動現有任務和專案,且省略 previewOnly 參數就會執行寫入。重要變更前應先要求預覽並核對結果,不要自動重試不確定的寫入。資料留在本機,但你的 MCP 用戶端與所選 AI 模型可能依各自的隱私條款傳輸工具輸入與結果。第三方 tap 中只應信任 FocusRelay 這一個 Homebrew formula。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 FocusRelay,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

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

[Demo: Ask an AI assistant about your OmniFocus tasks]

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?

On the development branch, Forecast questions support an explicit partial task-only scope. It includes past/today scheduled actions, flags, and the configured Forecast tag; it is not the native Forecast total and excludes calendar events and native visibility preferences. This requires the matching development binary and bridge, not the current Homebrew release.

Keep the assistant focused

The development candidate exposes ten model-facing tools: seven read tools plus edit_tasks, edit_projects, and add_tasks for supported changes. Task and subtask creation uses client-managed approval, optional preview, frozen date-only values, and mandatory verification. Omitted previewOnly performs a write; uncertain creation must not be automatically retried. See the creation contract. Earlier consolidation from seven editing tools to two reduced the catalog from 14 tools to 9 and cut context usage by 7–13% in controlled model tests. Those historical measurements do not measure the new creation tool's overhead. 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:

bash
brew tap deverman/focus-relaybrew trust --formula deverman/focus-relay/focusrelaybrew 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:

bash
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:

bash
focusrelay setup --dry-runfocusrelay 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:

bash
osascript -e 'tell application "OmniFocus" to quit'sleep 2open -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 Code configuration

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

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

--scope user makes FocusRelay available in every project on your Mac. Use --scope project instead 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:

bash
claude mcp list

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

OpenCode configuration example
json
{  "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:

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

Then ask:

How many flagged items do I have in OmniFocus?

Manual download or source build

Download the latest binary and FocusRelayBridge.omnijs from GitHub Releases, or build on macOS 26 or later with the Swift 6.3.3 toolchain selected by the checked-in .swift-version:

bash
git clone https://github.com/deverman/FocusRelayMCP.gitcd FocusRelayMCPswift build -c release./scripts/install-plugin.sh

After installing the plugin, restart OmniFocus completely and run focusrelay 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.

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

Run focusrelay --help for the command list. For write examples and safety rules, 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 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

CapabilityFocusRelayOmniFocus-MCPEnhancedOmnifocusMCPOperator
RuntimeNative Swift · HomebrewTypeScript · npxTypeScript · npxNative Rust · Homebrew; Python and TypeScript availablePython · uvx
OmniFocus accessBridge plug-in inside Omni Automation; documented APIsJXA and Omni Automation through osascriptOmni Automation through osascriptOmni Automation through osascriptInternal SQLite read cache; OmniJS fallback
Public MCP tools9, with seven read tools plus edit_tasks and edit_projects; 11 after planned creation tools #82 and #8312184511
Find, filter, and count tasks✅✅✅✅✅
Update existing tasks✅✅✅✅✅
Update existing projects✅✅✅✅◇ v1.5 roadmap
Preview and post-save verification✅ Every write tool; per-target results————
Drop projects without deleting them✅✅—✅—
Create tasks and subtasks🟡 #82✅✅✅✅
Create projects🟡 #83, including inbox-task conversion✅✅✅◇ v1.5 roadmap
Planned-date updates🟠 #16✅✅✅—
Repeating tasks🟠 #93✅—✅✅
Custom perspective contents🟠 #10✅✅——
Permanently delete tasks and projects—✅✅✅—

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

Help shape FocusRelay

See GitHub Issues for planned work. If FocusRelay earns a place in your workflow, star the repository so more OmniFocus 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 → Configure Plug-ins….
  3. Run focusrelay setup, quit OmniFocus completely, and reopen it.
  4. Run focusrelay setup --check-readiness.

Results look stale after an upgrade

The plugin JavaScript is cached by OmniFocus. Run focusrelay setup, restart OmniFocus completely, and check with focusrelay 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:

bash
focusrelay setup# Fully restart OmniFocusfocusrelay 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.

Development

bash
swift buildswift test

FocusRelay uses Swift Testing from the Swift toolchain. Production query changes must follow the documented Omni Automation contract.

License

FocusRelay is available under the MIT License.

來源:README.md,提交 cd2f8a7

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.10.0-beta最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分