How to set up Claude Code as a Godot co-developer

Guides · ~5 min read · 19 April 2026

godot-catalyst mcp claude-code

by Fireal Software · ~5 min read

Claude Code can read files, run shell commands, and edit code. What it can’t do out of the box is open a scene in Godot, add a Timer node to your player, connect a signal to a function, or reload a plugin. The editor is a black box to the agent.

This post walks through the setup that fixes that. Installing Godot Catalyst takes one command. After that Claude has 240+ tools for driving Godot 4.x directly.

Install

Requires Node.js 18+ and a Godot 4.x project.

npx godot-catalyst --install-addon /path/to/your/godot-project

The command copies the godot_catalyst EditorPlugin into your project’s addons/ folder. Open Godot, go to Project > Project Settings > Plugins, and flip the toggle next to Godot Catalyst. A new bottom panel labeled “Godot Catalyst” appears with the WebSocket port (default 6505) and a live call log.

That’s the plugin side. Now Claude Code needs to know about the MCP server.

Wire Claude Code to the server

Add this to ~/.claude/settings.json or .claude/settings.json in your project:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-catalyst"],
      "env": {
        "GODOT_PROJECT_PATH": "/path/to/your/godot/project"
      }
    }
  }
}

GODOT_PROJECT_PATH is the only required environment variable. It tells the server which project to inspect for offline file parsing and where LSP/DAP should resolve res:// paths.

Restart Claude Code. Run /mcp and you should see godot listed with a tool count in the 200s.

The first task: wire a signal with natural language

Open a scene in Godot, then tell Claude:

“Add a Timer node to my Player scene, set wait_time to 2 seconds, connect its timeout signal to a new function _on_attack_timer_timeout, and put a print there.”

What Claude actually does under the hood:

1. godot_get_current_scene to confirm Player.tscn is open
2. godot_create_node with parent_path: "Player", node_type: "Timer", node_name: "AttackTimer"
3. godot_set_node_properties to set wait_time to 2.0
4. godot_update_script to append func _on_attack_timer_timeout(): print("tick")
5. godot_connect_signal with from: "Player/AttackTimer", signal: "timeout", to: "Player", method: "_on_attack_timer_timeout"
6. godot_save_scene

Every step goes through the editor’s EditorUndoRedoManager, so Ctrl+Z rolls back the whole sequence. The status panel at the bottom of the editor shows each call as it lands.

The LSP and DAP bonus

Godot 4.x ships a GDScript Language Server on port 6005 and a Debug Adapter on port 6006. Both are off by default. Turn them on in Editor > Editor Settings > Network:

• Language Server > Enable — gives Claude godot_lsp_diagnostics, godot_lsp_completion, godot_lsp_hover, godot_lsp_definition, godot_lsp_references, godot_lsp_rename, godot_lsp_format
• Debug Adapter > Enable — gives Claude godot_debug_launch, godot_debug_set_breakpoints, godot_debug_step_over, godot_debug_variables, and the rest of the stepping tools

The LSP client lives at src/transport/lsp-client.ts and the DAP client at src/transport/dap-client.ts. Both speak Content-Length framed JSON-RPC to Godot’s built-in servers — no reinvention, just a thin bridge.

With LSP on, ask Claude “are there any errors in my project?” and it runs godot_lsp_diagnostics across your scripts. No need to open each file.

Tell Claude how to behave

Drop this into CLAUDE.md in your project root to make every session start right:

This project uses Godot 4.x with the godot-catalyst MCP server.

- Use godot_* tools for anything touching .tscn, .tres, .gd files
- Prefer batch_* tools when creating/modifying more than 3 nodes at once
- For closed-project analysis use godot_parse_tscn / godot_parse_tres
  (they work without the editor running)
- Every mutation is undoable via Ctrl+Z in the editor

This aligns with what AGENT_PROMPT.md in the Godot Catalyst repo already teaches the agent on startup, but repeating it in your project’s CLAUDE.md makes it stick across sessions.

When the WebSocket drops

If Claude’s tool calls start hanging or returning connection errors, the WebSocket between the TypeScript server and the plugin has died. Common causes:

• You hit Play and the editor got busy
• You toggled the plugin off and back on
• You reloaded the project (Project > Reload Current Project)

Check the bottom status panel. If it says “Disconnected”, re-enable the plugin in Project Settings > Plugins. The MCP server reconnects with exponential backoff (src/transport/connection-manager.ts handles the state machine). You rarely need to restart Claude Code itself.

Call godot_reload_handlers to hot-reload handler scripts without the full plugin-toggle cycle.