Ikuna

Ikuna MCP

AI クライアントを、Mac で実行中の Ikuna アプリのワークスペースコンテキストに接続します。

ikuna-mcp 0.1.1 は、公式 MCP Registry に io.github.RobertoHanas/ikuna-mcp として登録されています。

接続

1. npx を含む Node.js 18 以降をインストールします。
2. Ikuna を開き、設定 → AI 接続で共有する機能を有効にします。
3. ガイド付きセットアップを実行します。

npx -y ikuna-mcp setup

セットアップでは、Claude Desktop、Codex、Claude Code、Cursor を検出し、既存の設定には Ikuna の項目だけを追加して統合します。最新のバックアップを 3 つ保持し、ローカルの MCP ハンドシェイクを検証します。同じコマンドを再実行すると、古い値や欠落した値を修復できます。また、修復することを明示するには次のコマンドを実行します。

npx -y ikuna-mcp setup --repair
npx -y ikuna-mcp setup --client codex

終了ステータス 0 は、検出されたすべてのクライアントが設定され、ハンドシェイクに成功したことを示します。1 は設定が保存されたものの、検証に手動の操作が必要なことを示します。2 は、検出されたクライアントを設定できなかったことを示します。

自動検出されないクライアントの場合は、ほかのサーバー設定を残したまま、mcpServers の設定に次の項目を追加します。

"ikuna": { "command": "npx", "args": ["-y", "ikuna-mcp"] }

Claude Desktop、Claude Code、Cursor などのクライアントでは、完全な JSON 設定は次のようになります。

{
  "mcpServers": {
    "ikuna": {
      "command": "npx",
      "args": ["-y", "ikuna-mcp"]
    }
  }
}

Codex の場合は、~/.codex/config.toml に次の内容を追加します。

[mcp_servers.ikuna]
command = "npx"
args = ["-y", "ikuna-mcp"]
startup_timeout_sec = 30

保存後、MCP クライアントを再起動するか、再接続します。まず Ikuna の状態を確認するよう依頼し、次にワークスペースについて質問します。利用できるツールは、Ikuna で有効にした機能によって異なります。

初回実行時に、この小さなパッケージが npm からダウンロードされます。2 回目以降は npm のキャッシュが使われます。クライアントが npx を見つけられない場合は、command -v npx で表示される実行ファイルのフルパスを command として指定し、そのクライアントの PATH に Node.js が含まれていることを確認してください。

要件とトラブルシューティング

このパッケージは macOS 上でローカルに実行されます。Contents/bin/ikuna-mcp に MCP ヘルパーが含まれる Ikuna ビルドが必要です。

• Ikuna はインストール済みだが、終了している： Ikuna を開いて起動したままにし、MCP クライアントを再接続します。Ikuna が終了していると npm ブリッジはエラーで終了します。アプリを開くことはありません。
• Ikuna がインストールされていない： Ikuna 公式製品ページからインストールして開き、MCP クライアントを再接続します。
• MCP ヘルパーを利用できない： AI 接続に対応したビルドに Ikuna をアップデートします。
• 検出がタイムアウトする： Ikuna を終了して再度開き、もう一度試します。実行中のアプリの検出には短い期限が設定されており、エラーは stderr に出力されます。MCP の応答に混ざることはありません。
• 複数の Ikuna が起動している： 余分なコピーを終了します。すべてのコピーがローカルブリッジサービスを共有するため、同時に実行するインストールは 1 つにしてください。
• ツールを利用できない、または承認が必要： Ikuna の AI 接続設定で機能を確認します。このパッケージをインストールしても権限は変更されません。

カスタムのインストール場所は、実行中のアプリから自動検出されます。特定の実行中バンドルを明示的に選択するには、次のようにします。

"ikuna": {
  "command": "npx",
  "args": ["-y", "ikuna-mcp", "--app-path", "/Applications/Ikuna.app"]
}

IKUNA_APP_PATH は同等の環境変数です。選択するバンドルは、すでに実行中である必要があります。任意の環境変数 IKUNA_MCP_CLIENT_ID は接続管理のために Ikuna に渡されますが、アクセス権は付与されません。

仕組み

MCP client → npx ikuna-mcp → Ikuna.app/Contents/bin/ikuna-mcp → local XPC bridge → Ikuna

npm パッケージは実行中の Ikuna バンドルを検出し、クライアントの stdio ストリームを使って、バンドルに含まれるネイティブヘルパーを起動します。ネイティブヘルパーは署名付き XPC 接続、リクエストの期限、クライアントごとのプロトコルセッションを提供します。ツール、ワークスペースデータ、承認、変更は Ikuna が引き続き管理します。クライアントに応答を返す際、パッケージは tools/list のスキーマを修正し、任意の確認フィールドが任意のままになるようにします。これにより、厳格なクライアントが有効な読み取り呼び出しを拒否しないようにします。リクエスト、ワークスペースデータ、結果は変更しません。このパッケージには実行時依存関係がなく、ワークスペースデータベースを読み取らず、ネットワークリスナーも開きません。

MCP Registry マニフェストは server.json として含まれています。メンテナーは RELEASE.md に従って、npm パッケージとリスティングをまとめて公開できます。