MCP モードを使う¶

Koharu は通常のデスクトップアプリとしても、Web UI 付きの headless ローカルサーバーとしても、AI エージェント向け MCP サーバーとしても動作します。これらは別々のバックエンドではなく、どれも同じローカルランタイムと HTTP サーバーの上に乗っています。

モードが違っても変わらないこと¶

どの起動方法でも、ランタイムの基本形は同じです。

そのため、デスクトップ編集、headless 自動化、MCP ツールが挙動としてズレにくくなっています。

モード	デスクトップウィンドウ	ローカルサーバー	主な用途
Desktop	yes	yes	通常の対話編集
Headless	no	yes	ローカル Web UI、スクリプト、自動化
MCP	optional	yes	`/mcp` 経由のエージェント連携

インストールしたアプリを通常どおり起動します。

デスクトップモードでも、Koharu は内部でローカル HTTP サーバーを起動します。埋め込みウィンドウはパイプラインを直接呼ぶのではなく、このローカルサーバーと通信します。

これは既定モードであり、ほとんどのユーザーにはこの使い方が最適です。

headless モードでは、デスクトップ GUI を開かずにローカルサーバーだけを起動します。

# macOS / Linux
koharu --port 4000 --headless

# Windows
koharu.exe --port 4000 --headless

起動後、Web UI は http://localhost:4000 で開けます。

headless モードは停止するまで前面で実行され続け、通常は Ctrl+C で終了します。

既定では、Koharu はランダムなローカルポートを使います。ブックマーク、スクリプト、リバースプロキシ、MCP クライアントなどで安定したアドレスが必要なら --port を使ってください。

# macOS / Linux
koharu --port 9999

# Windows
koharu.exe --port 9999

--port を指定しなくてもサーバー自体は起動しますが、使用ポートは毎回変わります。

固定ポートで起動した場合、主なエンドポイントは次の通りです。

9999 は選んだポート番号に置き換えてください。

Koharu は loopback にバインドされるため、これらのエンドポイントは既定ではローカル専用です。別マシンからアクセスしたい場合は、自分でそのポートを公開する必要があります。

エンドポイントごとの詳細は HTTP API リファレンスを参照してください。

Koharu には、アプリ本体と同じドキュメント、モデル、ページパイプラインを共有する組み込み MCP サーバーがあります。

MCP クライアントやエージェントは次に向けます。

http://localhost:9999/mcp

これは、エージェントに次のような作業をさせたいときに便利です。

クライアントごとの設定例は MCP クライアントを設定するを参照してください。

組み込みツール一覧そのものは MCP ツールリファレンスにあります。

GPU 推論を明示的に無効にしたい場合は --cpu を使います。

# macOS / Linux
koharu --cpu

# Windows
koharu.exe --cpu

これは互換性確認、ドライバ問題の切り分け、GPU 周りが不確かなときの低リスクなデバッグに向いています。

アプリを起動せず、ランタイム依存物だけを事前取得したい場合は --download を使います。

# macOS / Linux
koharu --download

# Windows
koharu.exe --download

現在の実装では、この経路で初期化されるのは次です。

オプションのローカル翻訳 LLM までは事前取得されません。それらは設定で選んだ時点でダウンロードされます。

ログ付きでコンソール中心の起動をしたい場合は --debug を使います。

# macOS / Linux
koharu --debug

# Windows
koharu.exe --debug

Windows では、debug 実行と headless 実行の組み合わせにより、Koharu がコンソールウィンドウにアタッチするか、新しく作るかが変わります。