Godot MCP Setup with Claude Code: Step-by-Step Guide (2026)

Want Claude Code to run your Godot project, read the errors and fix them? A Godot MCP server gives it exactly that ability, and setup takes about five minutes.

This guide uses the open-source Coding-Solo godot-mcp server. It works with Godot closed and only needs Node.js.

30-second answer

1. Install Node.js 18+, Godot 4.x and Claude Code
2. Open a terminal in your project folder (the one with project.godot)
3. Run this command:

claude mcp add godot -- npx @coding-solo/godot-mcp

4. Start claude and ask: "Use the godot MCP server to get the Godot version."

If Godot is not on your PATH, add its location:

claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx @coding-solo/godot-mcp

What a Godot MCP server does

MCP (Model Context Protocol) is a standard way for an AI client to call tools on your computer. A Godot MCP server turns Godot actions (run the project, add a node, read debug output) into tools that Claude Code can use.

Without MCP, Claude can only edit your files. With it, Claude can also run the game and see what happened. That loop is what makes AI help useful for debugging.

Requirements

Check your versions:

node --version
claude --version
godot --version

If godot --version fails, that is fine. You can set GODOT_PATH in the next step.

Step 1: Add the server to Claude Code

From your project folder:

claude mcp add godot -- npx @coding-solo/godot-mcp

Choose a scope

For a team repo, share the setup:

claude mcp add --scope project godot -- npx @coding-solo/godot-mcp

Set GODOT_PATH (recommended on Windows)

The server tries to find Godot by itself. If it cannot, or you keep several versions, point it at the exact executable.

Windows (PowerShell):

claude mcp add godot -e GODOT_PATH="C:\Tools\Godot\Godot_v4.7-stable_win64.exe" -e DEBUG=true -- npx @coding-solo/godot-mcp

macOS:

claude mcp add godot -e GODOT_PATH=/Applications/Godot.app/Contents/MacOS/Godot -e DEBUG=true -- npx @coding-solo/godot-mcp

Linux:

claude mcp add godot -e GODOT_PATH=/usr/local/bin/godot -e DEBUG=true -- npx @coding-solo/godot-mcp

DEBUG=true turns on detailed server logs. It helps while you set things up, and you can remove it later.

Prefer a JSON config?

Put the same setup in .mcp.json in your project root:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@coding-solo/godot-mcp"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}

Claude Code asks you to approve project-scoped servers the first time you use them.

Build from source (optional)

Want a pinned local copy instead of npx?

git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp
npm install
npm run build

Then register the built file:

claude mcp add godot -- node /absolute/path/to/godot-mcp/build/index.js

Step 2: Verify the connection

claude mcp list

You should see godot with a Connected status. Inside Claude Code you can also type /mcp.

If that prints a version, Godot was found. If it fails, jump to the Troubleshooting section below.

Step 3: Try your first prompts

Open Claude Code in your project folder and try these in order.

The 14 tools at a glance

Run and debug

Project info

Scenes and assets

UIDs (Godot 4.4+)

New to UIDs? Our Godot 4.4 guide explains why they exist.

What it can and cannot do

This server drives Godot through the command line and project files. If you need Claude to see the live, open editor, look at a live-bridge add-on such as "Godot MCP Pro" or "Godot AI" in the Godot Asset Store. Those install as editor plugins and have their own setup. Start with Coding-Solo, then add a bridge only if you hit its limits.

Troubleshooting

claude mcp list shows "Failed to connect"

• Check node --version (it needs 18+)
• Run npx @coding-solo/godot-mcp by hand and read the error
• On native Windows, if npx will not start, try wrapping it: claude mcp add godot -- cmd /c npx @coding-solo/godot-mcp

"Godot not found" or the wrong version runs

Set GODOT_PATH to the exact executable. A wrong path can silently fall back to a different Godot on your PATH, so run get_godot_version and confirm it is the one you expect.

"Invalid project path"

The folder must contain a project.godot file. Start Claude Code from the project root, or give it the full path.

get_debug_output returns nothing

Call it a few seconds after run_project. Immediate calls can come back empty because the game has not printed anything yet.

Claude says it "ran fine" but the game is broken

A script error can still end with a clean exit. Ask Claude to quote the debug output instead of summarizing it.

I added godot twice and it conflicts

Server names must be unique. Remove the old entry first:

claude mcp remove godot

Edits do not show in the open editor

Enable Godot's external script reload (Editor Settings, Text Editor, Behavior, Files) if your version has it, or refocus the editor window.

Safety and good habits

• Use Git. Commit before you let an agent change scenes. git diff shows exactly what it touched
• Read permission prompts. Claude Code asks before tool calls by default. Do not blanket-approve a server you have not tested
• Playtest yourself. AI-written code still needs a human to try the game
• Know the engine's AI rule. Godot restricts AI-generated code in contributions to the engine itself. That policy does not stop you from using AI in your own game

FAQ

Does Claude Code work with Godot?

Yes. Claude Code edits your .gd and .tscn files directly, and an MCP server adds the ability to run the project and read its output.

Is the Godot MCP server free?

Coding-Solo's godot-mcp is open source under the MIT license. Claude Code itself needs its own Anthropic plan.

Do I need Godot 4.4 or newer?

For scene and run tools, a Godot 4 install is enough. The UID tools (get_uid, update_project_uids) require 4.4+.

Does it work with Godot 4.7?

Godot 4.7 is the current stable line at the time of writing. Point GODOT_PATH at the executable you use and run get_godot_version to confirm.

Can I use it with Cursor, Cline or Claude Desktop?

Yes. It is a standard MCP server, so the same command / args / env JSON works in other MCP clients. Cursor stores it in .cursor/mcp.json.

Can Claude Code write GDScript without MCP?

Yes. MCP is optional. It adds running, debugging and scene tools on top of normal file editing.

Bottom line

• Install: claude mcp add godot -- npx @coding-solo/godot-mcp
• Verify: claude mcp list, then call get_godot_version
• Windows: set GODOT_PATH explicitly
• Workflow: change, run, read output, fix, repeat
• Safety: commit first, so Git is your undo button

Once it works, AI help stops being "paste the error and hope" and becomes a real run-and-fix loop inside your project.

Resources:

• Coding-Solo/godot-mcp on GitHub
• Claude Code MCP documentation
• Model Context Protocol
• Use Claude, ChatGPT & Grok with Godot
• Godot MCP Server introduction
• Best Godot Plugins 2026