FocusRelay

FocusRelay — macOS 向けの高速な Swift 製 OmniFocus MCP サーバーと CLI

AI で一日の計画を立て、OmniFocus を最新の状態に保つ

FocusRelay は、高速なネイティブ Swift 製 MCP サーバーおよび CLI です。文書化された OmniFocus API を使用して、AI アシスタントが OmniFocus を読み取り、安全に更新できるようにします。

Homebrew でインストール · できることを見る · FocusRelay にスターを付ける · FocusRelay の改善に参加する

OmniFocus にすでにある作業について質問し、回答を確認して、長いタスクリストをクリックして回ることなく、承認した変更を加えられます。

質問する。確認する。更新する。

FocusRelay は、対象を絞った質問と簡潔な回答を想定して設計されているため、通常の依頼でアシスタントに OmniFocus のデータベース全体を渡す必要はありません。

次のようなプロンプトをお試しください。

• 「OmniFocus の受信箱を少しずつ整理するのを手伝ってください。」
• 「フラグ付きの項目はいくつありますか？」
• 「受信箱で最初に着手可能なタスクを3つ表示してください。」
• 「[task name] というタスクを見つけて、フラグを付け、変更を確認してください。」
• 「[task name] の期限を、現地時間で明日の午後5時に設定し、変更を確認してください。」

MCP サーバーのプロンプトを表示できるクライアントでは、process_inbox を選択してください。OpenCode では、/focusrelay:process_inbox を実行して、ガイド付きワークフローを開始します。 CLI ベースのエージェントは、focusrelay workflow get process_inbox でまったく同じ手順を取得できます。利用可能なワークフローは、全文を読み込まずに focusrelay workflow list で確認できます。

これらのワークフローは、OpenCode で複数の MCP 対応モデルを使ってテストされています。更新は安定した OmniFocus ID を対象とし、保存結果を確認できます。名前が重複している場合は、変更する前に候補を表示するよう依頼してください。

現在のリリースでは、次のことができます。

• 対応する MCP クライアントと CLI ベースのエージェントを、範囲を限定した承認優先の受信箱ワークフローに沿ってガイドする。
• 日付、フラグ、タグ、プロジェクト、着手可能かどうか、受信箱の状態、完了状況、見積もり、テキスト検索を使ってタスクを検索し、件数を数える。
• プロジェクト、フォルダ、タグ、タスク数、停滞している作業を確認する。
• 名前、メモ、フラグ、日付、見積もり、タグ、プロジェクト設定、レビュー間隔を更新する。
• OmniFocus のネイティブなレビュー日時と次回レビューのセマンティクスを使って、進行中および保留中のプロジェクトをレビュー済みにする。
• 既存のタスクをドロップ、復元、完了、再開、移動する。
• 既存のプロジェクトを完了、再開、状態変更、移動する。
• 変更案をプレビューし、保存結果を確認する。

現在のリリースでは、既存のタスクとプロジェクトを更新できます。項目の作成と削除には対応していません。作成機能は #82 および #83 で追跡されています。

FocusRelay を選ぶ理由

開発ブランチでは、Forecast に関する質問で明示的な タスクのみの部分スコープを指定できます。対象には、過去または今日に予定されているアクション、フラグ、設定済みの Forecast タグが含まれます。ネイティブな Forecast の合計ではなく、カレンダーイベントとネイティブの表示設定は対象外です。 これには、現行の Homebrew リリースではなく、対応する開発版バイナリとブリッジが必要です。

アシスタントが作業に集中できるようにする

FocusRelay がモデル向けに公開するツールは9つです。読み取りツールが7つ、対応する変更を行う edit_tasks と edit_projects がそれぞれ1つです。編集ツールを7つから2つにまとめたことで、ツールカタログ全体を14から9に減らし、管理されたモデルテストではコンテキスト使用量を7～13%削減しました。その分、ユーザーの実際の作業により多くの余地を残せます。 内部診断機能は CLI 内にとどめ、件数を返すコマンドでは長い項目リストを返さないようにし、フィールド選択によって応答を簡潔に保ちます。

実際のライブラリ規模で発揮するネイティブ Swift の速度

FocusRelay はネイティブ Swift としてコンパイルされ、Homebrew でインストールされます。リクエスト処理経路に Node.js や Python のランタイムはありません。単一パスのフィルタリングと早期終了ページネーションにより、テストでは数千件のタスク規模でも、対象を絞った受信箱の読み取りを約1秒で行えます。同じコアを使用する CLI では、正確でコンテキスト使用量の少ないクエリを実行できます。

OmniFocus がデータを認識する場所で実行

Swift サーバーは、OmniFocus の Omni Automation コンテキスト内で実行される軽量なブリッジプラグインに処理を振り分けます。ドキュメント化された API とネイティブのステータスを使用するため、プライベートデータベースを読み取ることなく、結果を OmniFocus と整合させられます。

確認できる変更を行う

編集ツールは安定した ID を対象とし、プレビュー、項目ごとの結果、簡潔な戻り値フィールド、任意の検証をサポートします。保存、更新、検証に失敗した場合は、成功ではなく失敗として報告されます。

FocusRelay は OmniFocus の処理を順番に行い、各更新が完了するまで待つようアシスタントに伝えます。また、リクエストが衝突しないよう、過負荷の状態を明確に報告します。MCP クライアントが切断されると、FocusRelay のプロセスはバックグラウンドに残らず、正常に終了します。

ユーザー向けの変更点とアップグレード要件については、最新のリリースノートをご覧ください。

プライバシーとセキュリティ

FocusRelay は Mac 上でローカルに実行されます。Swift サーバーは、ドキュメント化された API を通じて OmniFocus にアクセスするブリッジプラグインと、デバイス上で通信します。FocusRelay にはホスト型クラウドサービスがなく、OmniFocus のデータを FocusRelay が運営するサービスに送信することもありません。

MCP クライアントと選択した AI モデルは、それぞれのプライバシー規約に基づいてツールの入力と結果を送信する場合があります。機密データに FocusRelay を使用する前に、設定をご確認ください。

Homebrew で OmniFocus MCP サーバーをインストールする

要件：

• Apple silicon 搭載の macOS 26 以降；
• OmniFocus 4；
• Homebrew；
• MCP 対応のアシスタント、またはシェルを利用できる AI エージェント。

1. フォーミュラを信頼してインストールする

Homebrew 6 では、公式ではないタップのフォーミュラに対して明示的な信頼が必要です。FocusRelay のフォーミュラだけを信頼してから、インストールしてください：

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

フォーミュラ単位の信頼を設定すれば、タップ内の現在および将来のすべてのフォーミュラを信頼することなく、FocusRelay を許可できます。詳しくは、Homebrew のタップの信頼に関するドキュメントをご覧ください。

2. ガイド付きセットアップを実行する

インストールしたセットアップコマンドを実行します：

focusrelay setup

Homebrew にバンドルされたプラグインを見つけ、そのバージョンがバイナリと一致することを確認し、対応する OmniFocus プラグインフォルダをすべて検出して、コピーの許可を求める前にコピー元とコピー先をプレビューします。既存のプラグインは、置き換え用のコピーが正常に完了するまでそのまま残ります。セットアップを再実行すると、すでに最新のコピーも報告されます。

セットアップでは、クライアントに依存しない MCP コマンドと引数も表示されます。既知のクライアントの例を表示するには、--client claude-code、--client codex、または --client opencode を追加してください。FocusRelay は設定を表示しますが、設定自体は編集しません。

自動化する場合も、まず同じプランを確認してから、明示的にオプトインしてください：

focusrelay setup --dry-run
focusrelay setup --non-interactive

ソースからビルドする場合は、引き続き ./scripts/install-plugin.sh を使用してください。これは同じ Swift セットアップ実装を呼び出す、開発用の薄いエントリーポイントです。

3. OmniFocus を再起動する

OmniFocus を完全に終了してから再度開き、更新されたプラグインを読み込んでください：

osascript -e 'tell application "OmniFocus" to quit'
sleep 2
open -a "OmniFocus"

4. 準備状況を確認し、AI アシスタントに FocusRelay を追加する

FocusRelay は現在、Claude Code、 OpenCode、Codex CLI など、ターミナルから起動するターミナルベースの MCP クライアントに対応しています。Claude Desktop や ChatGPT のデスクトップアプリなどのデスクトップアプリケーションにはまだ対応していません。macOS により、FocusRelay が依存する OmniFocus データへのアクセスが制限されているためです。デスクトップアプリへの対応は #196 で追跡されています。

次の設定でローカルの stdio MCP サーバーを構成します。

• コマンド：/opt/homebrew/bin/focusrelay
• 引数：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
    }
  }
}

最初のクエリでは、OmniFocus からオートメーションの許可を求められます。スクリプトを実行 を選択してください。プロンプトが表示されない場合は、OmniFocus を前面に表示します。

OmniFocus を再起動した後、読み込まれたプラグインがバイナリと一致していることを確認します。

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

次に、次のように尋ねます。

OmniFocus にフラグ付きの項目はいくつありますか？

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

FocusRelay を OmniFocus MCP サーバーまたは CLI として使用する

MCP を使うと、対応するアシスタントが FocusRelay を検出し、適切なアクションを選択できます。CLI は、スクリプト、デバッグ、すでにシェルにアクセスできるエージェントに便利です。

以下の例は、現在の Homebrew リリースとソースビルドを対象としています。

# 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

# Preview a change without touching OmniFocus
focusrelay edit-tasks <task-id> \
  --operation update \
  --flagged true \
  --preview-only \
  --return-fields id,name,flagged

コマンドの一覧を確認するには、focusrelay --help を実行します。書き込みの例と安全ルールについては、CLI と MCP の安全な更新ワークフローを参照してください。

FocusRelay とほかの OmniFocus MCP サーバーの比較

FocusRelay は、ネイティブの Swift サーバーと、OmniFocus 内で実行されるブリッジプラグインを組み合わせています。Swift により MCP の処理を高速かつコンパクトに保ち、ブリッジにより最新のデータを取得し、文書化された OmniFocus API を通じて変更を適用します。

✅ 利用可能 · 🟡 次に対応予定 · 🟠 バックログ · ◇ プロジェクトのロードマップ · — 現時点で未文書化

この比較は、2026 年 7 月 15 日時点の各プロジェクトの公開ドキュメントに基づいています。「未文書化」は、その機能が実現不可能だという意味ではありません。他の公開 README には、対象ごとのプレビューと保存後の検証を組み合わせた同等の仕様は記載されていません。

プレビューでは、ID を解決し、保存せずに変更内容を検証します。検証は OmniFocus による保存後に実行され、影響を受けた値を読み戻し、不一致があれば失敗として報告します。これらは MCP ツールの引数なので、Codex、Claude Code、OpenCode などの標準的な stdio MCP クライアントで使用できます。ただし、モデルが指示されなくてもそれらを選ぶかどうかは、モデルとクライアントによって異なります。重要な変更では、「まずプレビューし、次に検証付きで適用してください」と指示してください。

FocusRelay の改善にご協力ください

予定されている作業については、GitHub Issues をご覧ください。FocusRelay がワークフローに役立つと思ったら、ほかの OmniFocus ユーザーにも見つけてもらえるよう、リポジトリにスターを付けてください。

協力したい方は、Issue を選ぶか、ユースケースを提案するか、対象を絞ったプルリクエストを送ってください。始めるには CONTRIBUTING.md をご覧ください。

トラブルシューティング

ブリッジがタイムアウトする

1. OmniFocus を最前面に表示し、最初の Run Script プロンプトを承認します。
2. Automation → Configure Plug-ins… で FocusRelay Bridge が有効になっていることを確認します。
3. focusrelay setup を実行し、OmniFocus を完全に終了してから再度開きます。
4. focusrelay setup --check-readiness を実行します。

アップグレード後に結果が古く見える

OmniFocus はプラグインの JavaScript をキャッシュします。focusrelay setup を実行して OmniFocus を完全に再起動し、focusrelay setup --check-readiness で確認してください。 プロジェクトとタグのカタログは 5 分間キャッシュされます。タスクのクエリは常に最新です。

プラグインとバイナリのバージョンが一致しない

Homebrew のフォーミュラをアップグレードするとバイナリは置き換えられますが、OmniFocus にインストール済みのプラグインのコピーはそのまま残ります。そのため、手順 2 を飛ばすと、プラグインのバージョンが何世代も古いままになることがあります。

ガイド付きセットアップをもう一度実行し、OmniFocus を再起動して、読み込まれたバージョンを確認してください。

focusrelay setup
# Fully restart OmniFocus
focusrelay setup --check-readiness

セットアップでは、ファイルを変更する前に、プラグインの同期が有効な場合は優先される iCloud の場所も含め、想定されるすべてのコピーが利用可能であることを確認します。また、置き換え用のコピーが配置され、検証されるまで、既存の各コピーを保持します。コピー先は 1 つずつ更新されるため、後のコピー先で失敗した場合、先のコピー先はすでに更新されていることがあります。報告された問題を修正し、OmniFocus を再起動する前にセットアップを再実行してください。準備状況が正常であれば、読み込まれたプラグイン、インストール済みのすべてのコピー、バイナリのバージョンが一致しています。

旅行後に時間に基づく結果がおかしく見える

MCP クライアントと OmniFocus を再起動し、FocusRelay が現在の macOS のタイムゾーンを認識するようにしてください。

開発

swift build
swift test

FocusRelay は Swift ツールチェーンの Swift Testing を使用します。本番環境のクエリに変更を加える場合は、文書化された Omni Automation の契約に従う必要があります。

ライセンス

FocusRelay は MIT ライセンスの下で利用できます。