Godot MCP

# Godot MCP Server A MCP server for AI assistants (Claude Code, Cursor, Codex etc) to control and access Godot Engine: capturing errors in editor, managing scenes, and remote connections allowing real-time build and debug - synchronized with your Godot editor. ## Setup ### Step 1: Install godot-mcp (one-time) ```bash git clone https://github.com/LeeSinLiang/godot-mcp.git ~/tools/godot-mcp cd ~/tools/godot-mcp npm install npm run build npm link ``` ### Step 2: Configure your Godot project (per-project) ```bash cd ~/my-games/your-godot-project godot-mcp-init ``` The tool will: 1. Ask for your Godot executable path 2. Select which clients to configure (Claude Desktop, Claude Code, Cursor) 3. Create configuration files automatically **That's it!** Start using AI assistance in Cursor or Claude Code. ## Features - **Project Management**: Launch editor, run/stop projects, list/inspect Godot projects - **Scene Editing**: Create scenes, add/configure nodes, load sprites, export mesh libraries - **Remote Debugging (Recommended)**: Connect to Godot editor's remote debugger, capture real-time output while running in editor - **Debug Output**: Get print statements, errors, and warnings from running projects - **Cross-Platform**: Windows, macOS, Linux support ## Available MCP Tools ### Remote Debugging Workflow (Recommended) Work seamlessly with the Godot editor while AI assists you: 1. **`connect_remote_debugger`** - Connect to Godot editor's remote debugger (default ports 6006/6007) 2. Press **F5** in Godot editor to run your project 3. **`get_remote_debug_output`** - Get real-time print statements, errors, and warnings 4. Make changes with AI assistance and test immediately in the editor This workflow allows you to: - Write code in Godot editor with syntax highlighting and autocomplete - Run and debug with F5 while AI monitors output and suggests fixes - No blind coding - see exactly what's happening in real-time ## All Available Tools **Debug & Remote:** `connect_remote_debugger`, `get_remote_debug_output`, `disconnect_remote_debugger`, `get_debug_output`, `capture_screenshot` **Project Management:** `launch_editor`, `run_project`, `stop_project`, `list_projects`, `get_project_info`, `get_godot_version` **Scene Editing:** `create_scene`, `add_node`, `load_sprite`, `save_scene`, `export_mesh_library` **UID Management (Godot 4.4+):** `get_uid`, `update_project_uids` ## Godot Executable Path Examples **Windows:** `C:\Program Files\Godot\Godot.exe` or `C:\Downloads\Godot_v4.5.1-stable_win64.exe\Godot_v4.5.1-stable_win64.exe` **macOS:** `/Applications/Godot.app/Contents/MacOS/Godot` **Linux:** `/usr/bin/godot` or `/usr/local/bin/godot` ## Troubleshooting ### "Failed to connect tool" or MCP server won't start **Most common cause:** Wrong Godot executable path in configuration. **Solution:** 1. Verify your Godot path by running: `"<your-godot-path>" --version` 2. Update the path in your config file: - **Claude Code:** Edit `.mcp.json` in your project directory - **Cursor:** Edit `.cursor/mcp.json` in your project directory - **Claude Desktop:** Check config in `%APPDATA%\Claude\` (Windows) or `~/Library/Application Support/Claude/` (macOS) 3. Restart your IDE/application after updating the config **Check logs:** - **Cursor:** Output panel → "MCP Logs" (Ctrl+Shift+U) - **Claude Code:** Terminal output or MCP logs ### Manual Configuration If you prefer manual setup, create config files: **Claude Code** - `.mcp.json` in project directory: ```json { "mcpServers": { "godot": { "command": "node", "args": ["/path/to/godot-mcp/build/index.js"], "env": { "GODOT_PATH": "/path/to/godot/executable" } } } } ``` **Cursor** - `.cursor/mcp.json` in project directory (same format as above) **Claude Desktop** - `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS): ```json { "mcpServers": { "godot": { "command": "node", "args": ["/path/to/godot-mcp/build/index.js"], "env": { "GODOT_PATH": "/path/to/godot/executable" } } } } ``` ## Development ```bash npm run build # Build the project npm run watch # Watch mode for development npm run inspector # Test with MCP inspector ```