Godot Mcp Server
About
Connect your favorite AI Chat to your Godot project!
Details
- Author
- tomyud1
- Downloads
- 466
- Categories
- Other
Jump to
- 32 tools across 6 categories (file, scene, script, project, asset generation, visualization)
- Interactive browser-based project map with real-time code editing
- Scene manipulation: create scenes, add/move nodes, set properties, attach scripts
- Script operations: apply code edits, validate syntax, rename files with reference updates
- Generate 2D sprites from SVG directly in the editor
- Supports Claude Desktop, Cursor, Claude Code, Cline, Windsurf, and any MCP client
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Godot Mcp ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install Node.js (one-time setup), then install the "Godot AI Assistant tools MCP" plugin from the Godot AssetLib. Add the server configuration (npx -y godot-mcp-server) to your MCP-compatible AI client (Claude Desktop, Cursor, Claude Code, Cline, Windsurf, etc.). Restart your AI client and restart your Godot project to see a green "MCP Connected" indicator in the editor's top-right corner.
get_godot_status
Check if Godot editor is connected to the MCP server.
get_guide
Read a short markdown guide from the server. Same content as the MCP resources/read protocol, exposed as a tool so it works in MCP clients that do not support resources (e.g. Claude Desktop, Cursor chat). Call with no args to list available guides: testing-loop, scene-editing, asset-generation, troubleshooting, tool-index. Call with {slug: "..."} to get the full markdown. Useful when a workflow is non-obvious (testing a running game, choosing between scene-editing tools, troubleshooting "Runtime helper not connected", etc.).
list_dir
List files and folders under a Godot project path (e.g., res://). Returns arrays of files and folders in the specified directory.
read_file
Read a text file from the Godot project, optionally a specific line range. Useful for reading GDScript files, scene files, or any text-based content.
search_project
Search the Godot project for a substring and return file hits with line numbers. Useful for finding usages of functions, variables, or any text pattern.
create_script
Create a NEW GDScript file (.gd) that does not exist yet. Use this for creating new scripts, NOT for editing existing files (use edit_script for edits). Use classdb_query to verify unfamiliar Godot class methods. After creating a script, consider using run_scene to test and get_errors to check for issues.
create_scene
Create a new Godot scene (.tscn) file with nodes. Use this to create player scenes, UI screens, game objects, etc.
read_scene
Read and parse a scene file to get its full node structure and properties. Use this to understand a scene before editing.
add_node
Add a node to an existing scene file. Supports an optional script attachment, group memberships, and a tree of children created in the same call (1 tool call instead of N). Children format: {name|node_name, type|node_type, properties?, script?, groups?, children?}. Both key styles are accepted so children can reuse the same keys you use at the top level (node_name, node_type) or the shorter form (name, type). Unknown child keys are rejected with a clear error.
remove_node
Remove a node from an existing scene file.
modify_node_property
Modify a single property on a node in a .tscn scene file. For multiple properties at once use set_node_properties. ALWAYS use a tool to modify .tscn files — NEVER edit them as text. To attach or change a script, use attach_script (NOT modify_node_property with property="script") — modify_node_property only rewrites the .tscn on disk, leaving the editor's in-memory node without the script, which makes connect_signal fail.
rename_node
Rename a node in a scene.
move_node
Move a node to a different parent in a scene and optionally control its position among siblings.
attach_script
Attach or change a script on a node in a scene.
detach_script
Remove a script from a node in a scene.
set_collision_shape
Create and assign a collision shape resource to a CollisionShape2D or CollisionShape3D node. Supports: CircleShape2D, RectangleShape2D, CapsuleShape2D, SphereShape3D, BoxShape3D, etc.
set_sprite_texture
Assign a texture resource to a Sprite2D / Sprite3D / TextureRect node in a .tscn scene file. Modes: • FromPath — load any texture file from disk (png/jpg/webp/svg/.tres) via load(). Returns whatever Texture2D the importer produced (usually CompressedTexture2D). Most common after generate_2d_asset. • ImageTexture (DEPRECATED ALIAS for FromPath, kept for back-compat) • NewImageTexture — force-create an ImageTexture (in-memory) from a raw image file. • PlaceholderTexture2D — in-scene placeholder of a given size. • GradientTexture2D / NoiseTexture2D — procedural textures. Response always includes texture_class (the actual Godot class the texture decoded to), width, height, and texture_path so the agent can confirm what landed without an extra get_resource_info call.
instance_scene
Add an instance of another scene (.tscn) as a child node. This is how you compose scenes from reusable parts (like prefabs). The instance maintains a live reference to the source scene. Use this instead of add_node when you want to reuse an existing scene.
set_mesh
Create and assign a mesh resource to a MeshInstance3D node. REQUIRED to make 3D geometry visible. Primitive types: BoxMesh, SphereMesh, CylinderMesh, CapsuleMesh, PlaneMesh, PrismMesh, TorusMesh, QuadMesh, TextMesh. Or load from file.
set_material
Create and assign a material to a MeshInstance3D, CSG, or GeometryInstance3D node. Supports StandardMaterial3D or loading from file.
get_node_spatial_info
Query computed 3D spatial data for a Node3D in a scene file. Returns local/global positions, scales, rotation quaternions, and subtree bounding boxes (AABB) when available. Use this before making precise 3D placement decisions.
measure_node_distance
Measure the world-space distance between two Node3D nodes in a scene file. Returns both the full 3D delta and the horizontal XZ distance.
snap_node_to_grid
Snap a Node3D position to a grid in local or global space. Useful for modular level building and keeping 3D scenes aligned.
set_node_properties
Set MULTIPLE properties on a node in a single tool call. Non-atomic: each property is applied independently; the response separates "applied" from "failed" so partial success surfaces clearly. Saves the scene once at the end. Resource-typed properties must use set_resource_property / set_sprite_texture / etc.
set_node_groups
Set, add, or remove a node's group memberships in a .tscn scene file. Groups persist to disk so the running game can call get_tree().get_nodes_in_group(name).
get_node_groups
Read the list of groups a node belongs to in a .tscn scene file.
find_nodes_in_group
Find every node in a .tscn that belongs to a given group. Returns paths, names, and types. Useful for verifying that level.gd will actually pick up the right nodes via get_tree().get_nodes_in_group().
set_resource_property
Modify a property on a Resource that is currently held by a node (or by another resource attached to that node). Use this to tweak shape radii, material colors, gradient stops, etc., WITHOUT recreating the resource. resource_path walks from the node down to the resource using "/"-separated property names, e.g. "shape", "material", or "material/next_pass". After the change, saves the scene.
save_resource_to_file
Save a Resource currently held by a node (or sub-resource) to a standalone .tres file so it can be referenced by other scenes / shared / committed. The node's property is then re-pointed to the loaded-from-disk version, so future set_resource_property calls write through to that file. Works for any Resource subclass: Material, Mesh, Shape, Curve, Gradient, etc.
get_resource_info
Inspect ANY Godot Resource. Two modes: • path mode: pass {path: "res://foo.png"} for a resource on disk (.tres / .res / image / .glb / .ogg / .tscn / etc.) • node mode: pass {scene_path, node_path, resource_property} to inspect a resource attached to a node WITHOUT having to save it as .tres first (e.g. the shape on a CollisionShape2D, the material on a MeshInstance3D, the stream on an AudioStreamPlayer). Returns class, file size (path mode), and type-specific info: width/height for textures, vertex/surface counts and AABB for meshes, length for AudioStream/Animation, node count for PackedScene, common Material properties, Shape extents, and the resource's dependencies.
list_signal_connections
List signal connections involving a node. source="scene_file" (default) reads connections persisted to a .tscn. source="runtime" requires the game to be running and reads live connections from the SceneTree. Use the runtime mode to verify dynamically-connected signals (those connected from code in _ready, not in the editor).
connect_signal
Connect a signal between two nodes inside a .tscn scene file. The target script must define the method (will refuse otherwise). Equivalent to clicking the "+" in the editor's Node > Signals panel and persists the connection to the .tscn. NOTE: scripts must be attached via attach_script (NOT via modify_node_property), otherwise the editor's in-memory node will not see the script and this tool will reject the connection.
disconnect_signal
Remove a signal connection from a .tscn scene file. No-op if the connection doesn't exist.
edit_script
Apply a SMALL, SURGICAL code edit (1-10 lines) to GDScript files. Auto-applies changes. For large changes, call multiple times. ONLY for .gd files - NEVER for .tscn scene files. Use classdb_query to verify unfamiliar Godot class methods. After making changes, consider using run_scene to test and get_errors to check for issues.
validate_script
Validate a GDScript file for syntax errors using Godot's built-in parser. Call after creating or modifying scripts to ensure they are error-free.
create_folder
Create a directory (with parent directories if needed).
delete_file
Permanently delete a file from the project. REQUIRES confirm=true as an explicit safety gate — omitting confirm returns an error. Creates a .bak backup alongside the original by default (disable with create_backup=false). REFUSES if the file is currently open in the editor (any scene tab or script editor tab); close the tab first, or pass force=true to bypass the check (not recommended — deleting the active scene out from under the editor can crash Godot). Use ONLY when deletion is explicitly requested; NEVER as a way to "edit" or "reset" a file (use edit_script instead). Does not delete directories.
rename_file
Rename or move a file, optionally updating references in other files.
list_scripts
List all GDScript files in the project with basic metadata.
get_project_settings
Concise project settings summary: main_scene, window size/stretch, physics tick rate, and render basics.
get_input_map
Return the full InputMap: built-in actions (ui_*, spatial_editor/*) plus all project-defined actions from project.godot. Each action maps to an object with "events" (array of key/mouse/gamepad bindings) and optionally "deadzone". Use this before configure_input_map to see current bindings and deadzones.
get_collision_layers
Return named 2D/3D physics collision layers from ProjectSettings.
get_node_properties
Get available properties for a Godot node type. Use this to discover what properties exist on a node type (e.g., anchors_preset for Control, position for Node2D).
get_console_log
Return the latest lines from the Godot editor output log.
get_errors
Get errors and warnings from both the Godot Output panel and the Debugger > Errors tab. Returns file paths, line numbers, severity, stack traces, and which source each error came from. If errors mention a missing method or property, use classdb_query to verify the correct API before fixing.
clear_console_log
Mark the current position in the Godot editor log. Subsequent get_console_log and get_errors calls will only return output after this point.
open_in_godot
Open a file in the Godot editor at a specific line (side-effect only).
scene_tree_dump
Dump the scene tree of the scene currently open in the Godot editor (node names, types, and attached scripts).
list_settings
Browse Godot project settings by category. Returns values from the editor's in-memory state — this matches project.godot after a normal Godot save, but direct edits to project.godot on disk are not reflected until the editor restarts (rescan_filesystem does not help). Call without a category to see all available categories. Call with a category to see all settings with their current values, types, and valid options.
update_project_settings
Update one or more Godot project settings. Pass a dictionary of setting paths to their new values. Use list_settings first to discover available setting paths, current values, and valid options for a category. For input action bindings, prefer configure_input_map — if you do pass input/* keys here, partial updates are merged safely (existing events are preserved).
configure_input_map
Add, remove, or replace input actions and their key/button bindings. Use get_input_map to see current actions before modifying.
run_scene
Launch a scene in the Godot editor. By default the call BLOCKS until the editor flips to playing state (so the next get_errors / take_screenshot / send_input call sees a real game). The response includes started, runtime_connected, wait_for_started_ms, wait_for_runtime_ms, scene_path, and runtime_root. Use runtime_root (e.g. "/root/Main") as the prefix for query_runtime_node node_path arguments — it is computed from the actual root node name in the .tscn, NOT from the file name. Set wait_for_runtime=true to additionally wait for the in-game MCPRuntime helper to connect (required before take_screenshot / send_input will work). Recommended testing loop: run_scene({wait_for_runtime:true}) → query_runtime_node / send_input / take_screenshot → get_errors → stop_scene.
stop_scene
Stop the currently running scene in the Godot editor. Always stop the scene before editing code to avoid errors repeating every frame.
is_playing
Compatibility shim: returns {playing, scene}. For richer info (uptime, runtime helper connectivity, last-launched target) prefer get_runtime_status.
get_runtime_status
Combined editor + runtime status snapshot. Returns playing, playing_scene, last_launched ("current"|"main"|res-path), uptime_ms since the most recent run_scene, and runtime_helper_connected (true once the in-game MCPRuntime autoload is talking to the MCP server).
wait
Sleep server-side. Useful between input events to let the game process them. Capped at 30000ms / 30s. Pass either ms or seconds (ms wins if both given).
take_screenshot
Capture the current viewport of the running game and save it as a PNG. REQUIRES the game to be running with the MCPRuntime autoload connected (run_scene with wait_for_runtime=true first). Returns resource_path, absolute_path, width, height, and (optionally) base64_png. Default save location is res://addons/godot_mcp/cache/screenshots/.
send_input
Synthesize an InputEvent and dispatch it to the running game via Input.parse_input_event. REQUIRES the game to be running with the MCPRuntime autoload connected. Use this to drive automated tests: click buttons, press keys, fire input actions. For multi-step interactions, alternate send_input → wait → query_runtime_node / take_screenshot.
query_runtime_node
Query a live node in the running scene tree. REQUIRES the game to be running with the MCPRuntime autoload connected. Returns class, path, valid, groups, and a map of property values. By default returns position, global_position, rotation, scale, visible, modulate — pass `properties:["..."]` to override. Set include_children=true to also list direct child nodes.
get_runtime_log
Return entries from the MCPRuntime in-game ring buffer. The buffer holds the last ~500 lines pushed via MCPRuntime.push_runtime_log(level, text) from your scripts plus internal connection events. For full engine stdout (script prints, errors, warnings) use get_console_log — the editor already captures the running game's stdout. Returns entries with ts_ms, level, and text plus started_at_ms (when the helper started) and now_ms.
classdb_query
Query Godot's ClassDB for class information: properties, methods, signals, and inheritance. Use this to verify that a class, method, or property actually exists in the running Godot engine before writing code. Prevents using wrong method names, outdated Godot 3 API, or incorrect signatures.
rescan_filesystem
Trigger a full filesystem rescan in the Godot editor. Use after creating, deleting, or modifying files externally (e.g. from the terminal or another tool). The scan is asynchronous and returns immediately.
setup_autoload
Register, unregister, or list autoload singletons. Autoloads are scripts/scenes loaded automatically at project start.
generate_2d_asset
Render an SVG to a PNG asset on disk via Image.load_svg_from_buffer. The SVG is rendered directly from bytes — no temp file is created, so concurrent calls are safe and project-rename quirks (user:// rebinding) cannot break it. Returns resource_path, absolute_path, dimensions {width,height}, and the render_scale used.
map_project
Crawl the entire Godot project and build an interactive visual map of all scripts showing their structure (variables, functions, signals), connections (extends, preloads, signal connections), and descriptions. Opens an interactive browser-based visualization.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"godot mcp server": {
"godot": {
"command": "npx",
"args": [
"-y",
"godot-mcp-server"
]
}
}
}
}McpServers
{
"godot": {
"command": "npx",
"args": [
"-y",
"godot-mcp-server"
]
}
}Godot MCP
Give your AI assistant full access to the Godot editor.
Build games faster with Claude, Cursor, or any MCP-compatible AI — no copy-pasting, no context switching. AI reads, writes, and manipulates your scenes, scripts, nodes, and project settings directly.
> Godot 4.x · 32 tools · Interactive project visualizer · MIT license
---
Quick Start
0. Install Node.js (one-time setup)
Download and run the installer from nodejs.org (LTS version). It's a standard installer — no terminal needed.
1. Install the Godot plugin
Inside the Godot editor, click the AssetLib tab at the top → search "mcp" → find "Godot AI Assistant tools MCP" → Install.
That's it — no manual file copying needed.
2. Add the server config to your AI client
Claude Desktop — Settings → Developer → Edit Config → open the config file and paste:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
Cursor — Settings → MCP → Add Server:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
Claude Code — run in terminal:
claude mcp add godot -- npx -y godot-mcp-server
Works with any MCP-compatible client (Cline, Windsurf, etc.)
3. Restart your AI client
Close and reopen Claude Desktop / Cursor / your client so it picks up the new config.
4. Restart your Godot project
Hit Restart Project in the Godot editor. Check the top-right corner — you should see MCP Connected in green. You're ready to go.
---
What Can It Do?
32 Tools Across 6 Categories
| Category | Tools | Examples |
|----------|-------|---------|
| File Operations | 4 | Browse directories, read files, search project, create scripts |
| Scene Operations | 11 | Create scenes, add/remove/move nodes, set properties, attach scripts, assign collision shapes and textures |
| Script Operations | 6 | Apply code edits, validate syntax, rename/move files with reference updates |
| Project Tools | 9 | Read project settings, input map, collision layers, console errors, scene tree dumps |
| Asset Generation | 1 | Generate 2D sprites from SVG |
| Visualization | 1 | Interactive browser-based project map |
Interactive Visualizer
Run map_project and get a browser-based explorer at localhost:6510:
- Force-directed graph of all scripts and their relationships
- Click any script to see variables, functions, signals, and connections
- Edit code directly in the visualizer — changes sync to Godot in real time
- Scene view with node property editing
- Find usages before refactoring
Limitations
AI cannot create 100% of a game by itself — it struggles with complex UI layouts, compositing scenes, and some node property manipulation. It's still in active development, so feedback is very welcome!
---
Architecture
┌─────────────┐ MCP (stdio) ┌─────────────┐ WebSocket ┌──────────────┐
│ AI Client │◄────────────────►│ MCP Server │◄─────────────►│ Godot Editor │
│ (Claude, │ │ (Node.js) │ port 6505 │ (Plugin) │
│ Cursor) │ │ │ │ │
└─────────────┘ │ Visualizer │ │ 32 tool │
│ HTTP :6510 │ │ handlers │
└──────┬───────┘ └──────────────┘
│
┌──────▼───────┐
│ Browser │
│ Visualizer │
└──────────────┘
---
Current Limitations
- Local only — runs on localhost, no remote connections
- Single connection — one Godot instance at a time
- No undo — changes save directly (use version control)
- No runtime control — can't press play or simulate input
- AI is still limited in Godot knowledge — it can't create 100% of the game alone, but it can help debug, write scripts, and tag along for the journey
---
Development
To build from source instead of using npm:
cd mcp-server
npm install
npm run build
Then point your AI client at mcp-server/dist/index.js instead of using npx.
---
License
MIT
---
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
