Registry / llm-agents / godot-mcp-server

godot-mcp-server

library1.0.2jsnpmunverified

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.

llm-agents http-networking

npm install godot-mcp-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GODOT-MCP-SERVER

godot-mcp-server

llm-agentsjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

main

✓ import { main } from 'godot-mcp-server'

✗ const GodotMCP = require('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

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

✗ import GodotMCPServer from 'godot-mcp-server'

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

ToolRegistry

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

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

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

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"] } } }

Debug

Known issues

breakingFrom 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.

affects: >=0.5.0

deprecatedThe '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.

affects: >=0.5.0

gotchaThe 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.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

npx cache or global install missing

fix

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

MCP server disconnected: WebSocket connection failed

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).

Tool execution error: parent_path is required

Missing or malformed parent_path argument in scene tool

fix

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

Forbidden path traversal detected

Attempted to read/write a file outside the project directory

fix

Only access files within the opened Godot project folder.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredMCP protocol implementation

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tomyud1/godot-mcp ↗

packagehttps://www.npmjs.com/package/godot-mcp-server ↗

homepagehttps://godot-mcp-server.com ↗