LeeSinLiang/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)

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)

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:

{
  "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):

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/build/index.js"],
      "env": { "GODOT_PATH": "/path/to/godot/executable" }
    }
  }
}

Development

npm run build      # Build the project
npm run watch      # Watch mode for development
npm run inspector  # Test with MCP inspector