Troubleshooting

Connection refused / ping fails

Make sure Unreal Editor is running with the ClaudeUnreal plugin enabled. The TCP bridge listens on 127.0.0.1:55557 — if another process bound the port, or a firewall blocks localhost, the ping will fail.

• Confirm the plugin loaded: Edit → Plugins → Installed → ClaudeUnreal is checked.
• Close other editor instances — only one listener per port.
• Check .mcp.json in your project root exists and points to claude_unreal_server.py inside the plugin’s Resources/MCP/ directory.

Python dependencies missing

The server runs under uv run, which resolves dependencies on first invocation. If it can’t reach PyPI, resolution fails.

• Ensure python and uv are on PATH (python --version, uv --version).
• If offline, pre-install dependencies: uv pip install -r Resources/MCP/requirements.txt.

Tool returns an error

Check the editor’s Output Log (Window → Developer Tools → Output Log). Filter by ClaudeUnreal to see bridge-side diagnostics.

Note

Many tool errors trace back to asset path typos — use find_assets to discover the correct path. See Asset paths for the format.

Asset paths not found

Use find_assets (wildcard) or browse_content_path (directory listing) to discover real paths. Don’t guess — paths are case-sensitive and include the asset’s object name after the dot (/Game/MyAsset.MyAsset).

Still stuck

Open an issue at github.com/echoulen/claude-unreal with:

• Your UE5 version and OS.
• The tool call that failed.
• The relevant Output Log excerpt.

cu CLI connection issues

If cu exec ... fails with a connection error, run cu doctor first:

cu doctor

Output includes:

• manifest path — where the bundled command list lives.
• manifest commands — the count must be > 0; if 0, the manifest is missing or unreadable.
• bridge_commit — the git short SHA the manifest was generated against; if it diverges from your installed plugin, regenerate.
• bridge port — defaults to 127.0.0.1:55557. Override with cu --port N.
• editor: connected (pong) vs editor: UNREACHABLE — … — the latter usually means UE Editor is not running, or the plugin is disabled in Edit → Plugins.

Common error messages:

• Could not reach Unreal Editor at 127.0.0.1:55557 — open the editor, or check that ClaudeUnreal is enabled.
• command 'X' is in bridge but missing from manifest — manifest is stale; pull main or run python3 web/scripts/extract-tools.py.
• error: missing required: <name> — fix the cu exec call (check cu help <command> for the schema).