UniMCP4CC

# Claude Code Connection Guide Unity MCPサーバーとClaude Codeを接続するためのガイドです。 --- ## 🚀 クイックセットアップ（推奨） ### ワンクリックセットアップ 1. **Unity Editorを開く** 2. **Window > Unity MCP > Setup Claude Code** を選択 3. **Generate Configuration** ボタンをクリック 4. **Install npm packages** ボタンをクリック（初回のみ） 5. **Claude Codeを再起動** これだけで接続完了です。 --- ## 📋 チェックリスト ### ✅ 1. Unity MCP Serverパッケージの確認 **確認方法：** ```bash # パッケージがインストールされているか確認 ls Packages/com.local.mcp.unityserver # または ls Library/PackageCache/com.local.mcp.unityserver* ``` **推奨バージョン：** v0.7.2以降 **インストール方法（未インストールの場合）：** 1. Unity Editorを開く 2. **Window > Package Manager** 3. **+** > **Add package from git URL...** 4. 入力: `git@github.com:dsgarage/CC2UniMCP.git` --- ### ✅ 2. mcp-bridgeのセットアップ **mcp-bridgeとは？** Claude Code（stdio）とUnity Editor（HTTP）の間を橋渡しするNode.jsプログラムです。 ``` Claude Code (stdio) → mcp-bridge (Node.js) → Unity Editor (HTTP) ``` **自動セットアップ（推奨）：** 1. Unity Editorを開く 2. **Window > Unity MCP > Setup Claude Code** を選択 3. **Generate Configuration** をクリック 4. **Install npm packages** をクリック **手動セットアップ（必要な場合）：** ```bash # パッケージ内のServer~/mcp-bridgeに移動 cd Library/PackageCache/com.local.mcp.unityserver@*/Server~/mcp-bridge # 依存関係をインストール npm install ``` **確認：** ```bash ls Library/PackageCache/com.local.mcp.unityserver@*/Server~/mcp-bridge/ # 以下が存在するはず: # - index.js # - package.json # - node_modules/ ``` --- ### ✅ 3. Unity Editorの起動とサーバー確認 **Unity Editorでプロジェクトを開く** Unity Editorを起動すると、自動的にMCPサーバーが起動します。 **Unity Consoleで確認：** ``` [MCP] Servers auto-started on Unity Editor launch [MCP] WebSocket: ws://localhost:5050 [MCP] HTTP API: http://localhost:5051 ``` **ランタイム設定ファイルの確認：** ```bash cat /path/to/YourUnityProject/.unity-mcp-runtime.json ``` 出力例： ```json { "projectName": "YourProject", "projectPath": "/path/to/YourUnityProject", "unityVersion": "6000.2.8f1", "wsPort": 5050, "httpPort": 5051, "serverVersion": "0.4.12", "timestamp": "2025-11-13T10:00:00Z" } ``` **HTTPサーバーの動作確認：** ```bash # ヘルスチェック curl http://localhost:5051/health # 期待される出力: # {"status":"ok","projectName":"YourProject","unityVersion":"6000.2.8f1"} ``` **トラブルシューティング：** | 問題 | 原因 | 対処法 | |------|------|--------| | `.unity-mcp-runtime.json`がない | Unity Editorが起動していない | Unity Editorを起動 | | `/health`が応答しない | サーバーが起動していない | Unity Consoleでエラーを確認 | | ポート番号が違う | ポートが既に使用中 | `.unity-mcp-runtime.json`のポート番号を確認 | --- ### ✅ 4. Claude Code設定ファイル **設定ファイルのパス：** ``` ~/.config/claude/claude_desktop_config.json ``` **正しい設定内容：** ```json { "mcpServers": { "unity": { "command": "node", "args": ["/絶対パス/YourUnityProject/mcp-bridge/index.js"], "env": { "MCP_VERBOSE": "false" } } } } ``` **重要なポイント：** 1. **絶対パスを使用すること** - ❌ `"args": ["./mcp-bridge/index.js"]` - ❌ `"args": ["~/Projects/Unity/mcp-bridge/index.js"]` - ✅ `"args": ["/Users/username/Projects/Unity/YourProject/mcp-bridge/index.js"]` 2. **パスに存在確認** ```bash # このコマンドが成功するか確認 node /絶対パス/YourUnityProject/mcp-bridge/index.js ``` 3. **複数のUnityプロジェクトがある場合** ```json { "mcpServers": { "unity-project1": { "command": "node", "args": ["/path/to/Project1/mcp-bridge/index.js"] }, "unity-project2": { "command": "node", "args": ["/path/to/Project2/mcp-bridge/index.js"] } } } ``` --- ### ✅ 5. Claude Codeの完全再起動 **重要：** 設定ファイルを編集したら、必ずClaude Codeを**完全に終了**して再起動してください。 **macOS:** ```bash # Claude Codeを完全終了 pkill -9 "Claude" # Claude Codeを再起動 open -a "Claude" ``` **または：** - Command + Q でClaude Codeを終了 - Dockから完全に削除されたことを確認 - 再度起動 --- ## 🐛 よくある問題と解決策 ### 問題1: MCPツールが全く表示されない **症状：** - Claude Codeを開いてもUnity MCPツールが表示されない - エラーメッセージも表示されない **原因：** - Claude Code設定ファイルが読み込まれていない - パスが間違っている **解決策：** 1. **設定ファイルの存在確認** ```bash cat ~/.config/claude/claude_desktop_config.json ``` 2. **JSON構文エラーのチェック** ```bash # JSON構文が正しいか検証 python3 -m json.tool ~/.config/claude/claude_desktop_config.json ``` 3. **Claude Codeのログ確認** ```bash # macOS tail -f ~/Library/Logs/Claude/main.log ``` 4. **mcp-bridgeを直接テスト** ```bash cd /path/to/YourUnityProject/mcp-bridge echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | node index.js ``` --- ### 問題2: "Unity Editor is not running" エラー **症状：** ``` ❌ Unity Editor is not running or not responding Please ensure: 1. Unity Editor is open 2. Unity MCP Server package (v0.4.12+) is installed ... ``` **原因：** - Unity Editorが実際に起動していない - Unity MCPサーバーが起動に失敗している - ポート番号が間違っている **解決策：** 1. **Unity Editorが起動しているか確認** 2. **Unity Consoleでエラーをチェック** - コンパイルエラーがあるとMCPサーバーが起動しない 3. **ポート番号の確認** ```bash # .unity-mcp-runtime.jsonのhttpPortを確認 cat /path/to/YourUnityProject/.unity-mcp-runtime.json ``` 4. **ポートが使用可能か確認** ```bash lsof -i :5051 # 何も表示されなければポートは空いている ``` 5. **Unity Editorを再起動** --- ### 問題3: ツールリストは表示されるが、実行するとエラー **症状：** - MCPツール一覧は表示される - ツールを実行するとタイムアウトやエラーが発生 **原因：** - Unity Editorが応答していない - Play Modeで実行中（Editor APIが使用不可） - Unity APIのエラー **解決策：** 1. **Play Modeを停止** 2. **Unity Consoleでエラーログを確認** ``` [MCP] Error: ... ``` 3. **HTTPエンドポイントを直接テスト** ```bash curl -X POST http://localhost:5051/api/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "unity.scene.list", "params": {"maxDepth": 1}, "id": 1 }' ``` --- ### 問題4: Node.jsエラー **症状：** ``` Error: Cannot find module '@modelcontextprotocol/sdk' ``` **原因：** - npm依存関係がインストールされていない **解決策：** ```bash cd /path/to/YourUnityProject/mcp-bridge npm install ``` --- ### 問題5: 複数のUnityプロジェクトで切り替えられない **症状：** - プロジェクトを切り替えてもClaude Codeが古いプロジェクトに接続している **原因：** - Claude Code設定が単一のプロジェクトを指している **解決策：** **方法1: 環境変数で切り替え** ```bash # プロジェクトごとにスクリプトを作成 # ~/launch-claude-project1.sh export UNITY_PROJECT_PATH="/path/to/Project1" open -a "Claude" ``` **方法2: 複数のMCPサーバーを登録** ```json { "mcpServers": { "unity-game1": { "command": "node", "args": ["/path/to/Game1/mcp-bridge/index.js"] }, "unity-game2": { "command": "node", "args": ["/path/to/Game2/mcp-bridge/index.js"] } } } ``` Claude Code内でプロジェクトを指定： ``` @unity-game1 シーンのGameObjectを一覧表示 ``` --- ## 🚀 確実に動作させるためのステップバイステップガイド ### ステップ1: クリーンインストール ```bash # 1. Unityプロジェクトのルートに移動 cd /path/to/YourUnityProject # 2. 既存のmcp-bridgeを削除（ある場合） rm -rf mcp-bridge # 3. Unity MCP Serverパッケージを最新版に更新 # Unity Editor: Window > Package Manager > Unity MCP Server > Update # 4. mcp-bridgeをセットアップ cp Packages/com.local.mcp.unityserver/mcp-bridge-template/setup-mcp-bridge.sh . bash setup-mcp-bridge.sh ``` ### ステップ2: Unity Editorの起動 ```bash # 1. Unity Editorでプロジェクトを開く # 2. Unity Consoleで起動メッセージを確認 # [MCP] Servers auto-started on Unity Editor launch ``` ### ステップ3: 接続テスト ```bash # 3. HTTPサーバーの動作確認 curl http://localhost:5051/health # 4. 正しい出力が返ってくることを確認 # {"status":"ok",...} ``` ### ステップ4: Claude Code設定 ```bash # 5. 設定ファイルを作成/編集 nano ~/.config/claude/claude_desktop_config.json # 6. 絶対パスで設定 # { # "mcpServers": { # "unity": { # "command": "node", # "args": ["/絶対パス/mcp-bridge/index.js"] # } # } # } # 7. JSON構文をチェック python3 -m json.tool ~/.config/claude/claude_desktop_config.json ``` ### ステップ5: Claude Code再起動 ```bash # 8. Claude Codeを完全終了 pkill -9 "Claude" # 9. Claude Codeを起動 open -a "Claude" # 10. MCPツールが表示されることを確認 ``` --- ## 📊 診断チャート ``` Claude CodeがUnity MCPを認識しない ↓ ┌─────────────────────────┐ │ Unity Editorは起動中？ │ └─────────────────────────┘ │No │Yes ↓ ↓ Unity Editorを ┌─────────────────────────┐ 起動する │ Unity Consoleに │ │ "[MCP] Servers..."表示？│ └─────────────────────────┘ │No │Yes ↓ ↓ コンパイル ┌──────────────────┐ エラーを修正 │ mcp-bridgeは？ │ └──────────────────┘ │No │Yes ↓ ↓ setup-mcp ┌────────────────┐ -bridge.sh │ Claude Code │ を実行 │ 設定は正しい？ │ └────────────────┘ │No │Yes ↓ ↓ 設定を Claude Code 修正 を再起動 ↓ 動作確認 ``` --- ## 🔧 高度なトラブルシューティング ### デバッグログの有効化 **mcp-bridge側：** ```json { "mcpServers": { "unity": { "command": "node", "args": ["/path/to/mcp-bridge/index.js"], "env": { "MCP_VERBOSE": "true" } } } } ``` **Unity側（GlobalLogCapture.cs）：** Unity Consoleで詳細ログが表示されます。 ### ネットワーク接続の確認 ```bash # Unityサーバーにリクエストを送信 curl -v -X POST http://localhost:5051/api/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "unity.connection.status", "params": {}, "id": 1 }' ``` ### プロセスの確認 ```bash # Node.jsプロセスがindex.jsを実行しているか確認 ps aux | grep "index.js" # Unity Editorプロセスを確認 ps aux | grep "Unity" ``` --- ## 📞 サポート それでも問題が解決しない場合： 1. **診断スクリプトの出力を保存** ```bash bash diagnose-connection.sh > diagnosis.txt 2>&1 ``` 2. **GitHubでIssueを作成** - リポジトリ: https://github.com/dsgarage/CC2UniMCP - 診断スクリプトの出力を添付 - Unity Consoleのエラーログを添付 3. **必要な情報** - Unity MCP Serverバージョン - Unity Editorバージョン - Node.jsバージョン - OS情報 --- ## ✅ 接続成功の確認 以下がすべて**YES**なら正常に動作しています： - [ ] Unity Consoleに`[MCP] Servers auto-started`が表示される - [ ] `curl http://localhost:5051/health`が成功する - [ ] `.unity-mcp-runtime.json`が存在する - [ ] `mcp-bridge/node_modules`が存在する - [ ] Claude Code設定ファイルにunityサーバーが登録されている - [ ] Claude Codeを再起動した - [ ] Claude Code内でUnity MCPツールが表示される - [ ] ツールを実行してUnity側で動作する **すべてクリアすれば、Claude CodeからUnityを完全に制御できます！**