Godot MCP Server

0.5.0 verified Sat Apr 25 auth: no javascript

MCP server for Godot game engine integration, enabling AI assistants like Claude and Cursor to manipulate Godot scenes, scripts, nodes, and project settings in real time. Current stable version 0.5.0, released March 2025, with monthly updates. Provides 32 tools across 6 categories (file, scene, script, project operations, asset generation, visualization) plus an interactive web-based project map. Unlike generic file-editing MCP servers, it communicates via WebSocket with the Godot editor plugin for live project state access, allowing direct editing of runtime properties and node trees without file system guesswork. TypeScript-first with full ESM support, designed for Godot 4.x.

Common errors

error Error: Cannot find module 'godot-mcp-server' ↓

cause npx cache or global install missing

fix

Run 'npx -y godot-mcp-server' with the -y flag to auto-install.

error MCP server disconnected: WebSocket connection failed ↓

cause Godot editor not running or plugin not enabled

fix

Start Godot with project loaded and ensure Godot MCP plugin is enabled (Project > Project Settings > Plugins).

error Tool execution error: parent_path is required ↓

cause Missing or malformed parent_path argument in scene tool

fix

Provide full absolute node path, e.g., 'parent_path': '/root/Main'.

error Forbidden path traversal detected ↓

cause Attempted to read/write a file outside the project directory

fix

Only access files within the opened Godot project folder.

Warnings

breaking From v0.5.0, the 'scene_add_node' tool changed signature: 'parent_path' is now required and must be a full node path (e.g., /root/Main/Player) instead of relative. ↓

fix Update calls to include full absolute path for parent_path.

deprecated The 'get_scene_tree' tool is deprecated in v0.5.0, replaced by 'dump_scene' which provides richer node property data. ↓

fix Replace get_scene_tree with dump_scene.

gotcha The Godot plugin must be running and connected on WebSocket port 6505. If the plugin is not enabled, the server will start but tools will fail with 'Plugin not connected'. ↓

fix Ensure the Godot MCP plugin is enabled in Project Settings > Plugins and Godot is running.

gotcha The server only works locally (localhost). It does not support remote connections; attempting to connect from another machine will silently fail. ↓

fix Run the AI client and Godot on the same machine.

Install

npm install godot-mcp-server

yarn add godot-mcp-server

pnpm add godot-mcp-server

Imports

main
wrong
```
const GodotMCP = require('godot-mcp-server')
```
correct
```
import { main } from 'godot-mcp-server'
```
Package exports a main() function; there is no default export. Also, the primary use is CLI via npx, not programmatic import.

GodotMCPServer

wrong

import GodotMCPServer from 'godot-mcp-server'

correct

import { GodotMCPServer } from 'godot-mcp-server/lib/server'

Internal class, not directly exported from root. Use only if extending the server.

ToolRegistry

wrong

import { Tools } from 'godot-mcp-server'

correct

import { ToolRegistry } from 'godot-mcp-server/lib/tools'

Tool registry is a separate export; check lib/tools for available tool classes.

Quickstart

Configuration for Claude Desktop or Cursor to enable godot-mcp-server. Copy this JSON into the MCP settings file.

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-server"]
    }
  }
}