Summary
Connects Claude or Cursor directly to the Godot 4.x editor via WebSocket, exposing 42 tools across scene manipulation, script editing, project settings, and runtime control. You can create nodes, attach scripts, modify properties, run scenes, and query the ClassDB without leaving your AI chat. Ships with a browser based project visualizer that maps script relationships and lets you edit code with live sync back to Godot. Installation is a plugin drop in plus an npx command in your MCP config. Best when you're prototyping game mechanics, refactoring GDScript, or need AI to read and modify scene trees while you work. No remote connections, one instance at a time, changes save directly.
Install to Claude Code
verifiedclaude mcp add godot-mcp -- npx -y godot-mcp-serverRun in your terminal. Replace YOUR_* placeholders with real values; add --scope user to install for every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Verified live against the running server on Jun 11, 2026.
verified live65 tools
get_godot_statusCheck if Godot editor is connected to the MCP server.
Check if Godot editor is connected to the MCP server.
No parameters — call it with no arguments.
get_guideRead 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,...1 params
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,...
Parameters* required
slugstringGuide slug. Omit to list all available guides. Known slugs: testing-loop, scene-editing, asset-generation, troubleshooting, tool-index.
list_dirList files and folders under a Godot project path (e.g., res://). Returns arrays of files and folders in the specified directory.1 params
List files and folders under a Godot project path (e.g., res://). Returns arrays of files and folders in the specified directory.
Parameters* required
root*stringStarting path like res://addons/ai_assistant or res://
read_fileRead a text file from the Godot project, optionally a specific line range. Useful for reading GDScript files, scene files, or any text-based content.3 params
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.
Parameters* required
path*stringres:// path to the file (e.g., res://scripts/player.gd)
end_linenumberInclusive end line; 0 or missing means to end of file (optional)
start_linenumber1-based inclusive start line (optional)
search_projectSearch the Godot project for a substring and return file hits with line numbers. Useful for finding usages of functions, variables, or any text pattern.2 params
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.
Parameters* required
globstringOptional glob filter like **/*.gd to search only GDScript files
query*stringCase-insensitive substring to find
create_scriptCreate 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 ge...2 params
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 ge...
Parameters* required
path*stringScript file path (res://scripts/player.gd) - must not exist yet
content*stringFull GDScript content to write to the file
create_sceneCreate a new Godot scene (.tscn) file with nodes. Use this to create player scenes, UI screens, game objects, etc.5 params
Create a new Godot scene (.tscn) file with nodes. Use this to create player scenes, UI screens, game objects, etc.
Parameters* required
nodesarrayArray of child nodes to add. Each node spec: {name|node_name, type|node_type, properties?, script?, groups?, children?}. Use either {name, type} or the same {node_name, node_type} keys used at the top level — both work. Unknown keys (e.g. "class", "kind", "parent") return an error instead of silently producing a generic Node.
scene_path*stringScene file path (e.g., res://Scenes/player.tscn)
attach_scriptstringOptional script path to attach to root node (res://path/to/script.gd)
root_node_namestringName of root node (default: derived from filename)
root_node_type*stringType of root node (e.g., Node2D, CharacterBody2D, Control, Node3D). REQUIRED.
read_sceneRead and parse a scene file to get its full node structure and properties. Use this to understand a scene before editing.2 params
Read and parse a scene file to get its full node structure and properties. Use this to understand a scene before editing.
Parameters* required
scene_path*stringPath to the scene file (res://path/to/scene.tscn)
include_propertiesbooleanInclude node properties in the output (default: false)
add_nodeAdd 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 st...8 params
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 st...
Parameters* required
groupsarrayOptional list of node groups this node should belong to. Persisted to the .tscn file.
scriptstringOptional script path to attach to the new node (res://path/to/script.gd)
childrenarrayOptional tree of children to create under the new node. Each entry has the same shape as add_node's args (minus parent_path). Use this to build sub-trees in one call.
node_name*stringName for the new node
node_type*stringType of node (e.g., Sprite2D, Camera2D, RigidBody2D, CollisionShape2D)
propertiesobjectOptional dictionary of properties to set on the node
scene_path*stringPath to the scene file (res://path/to/scene.tscn)
parent_pathstringPath to parent node (. for root, or relative path like Sprite2D)
remove_nodeRemove a node from an existing scene file.2 params
Remove a node from an existing scene file.
Parameters* required
node_path*stringPath to the node to remove (cannot be root, use relative path)
scene_path*stringPath to the scene file
modify_node_propertyModify 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...4 params
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...
Parameters* required
value*valueNew value for the property. ANY JSON value accepted: primitives (numbers, strings, booleans, null), arrays, or objects. Use the {type, ...} discriminated form for Godot variant types. Common forms: numeric (e.g. 1.5), boolean (true), string ("hello"), Vector2 ({type:"Vector2",x,y}), Vector3 ({type:"Vector3",x,y,z}), Color ({type:"Color",r,g,b,a}), Quaternion ({type:"Quaternion",x,y,z,w}), Basis ({type:"Basis",euler:{x,y,z}}), Transform3D ({type:"Transform3D",basis:{...},origin:{x,y,z}}), AABB ({type:"AABB",position:{x,y,z},size:{x,y,z}}), Rect2 ({type:"Rect2",x,y,width,height}), NodePath (string starting with "."). For Resource-typed properties (Texture2D, Mesh, Material, Shape, etc.) DO NOT pass values here — use set_resource_property, set_sprite_texture, set_mesh, set_material, or set_collision_shape.
node_pathstringPath to the node (. for root, or relative path like "Sprite2D")
scene_path*stringPath to the .tscn scene file
property_name*stringName of the property to modify (position, scale, rotation, modulate, visible, etc.)
rename_nodeRename a node in a scene.3 params
Rename a node in a scene.
Parameters* required
new_name*stringNew name for the node
node_path*stringPath to the node to rename
scene_path*stringPath to the scene file
move_nodeMove a node to a different parent in a scene and optionally control its position among siblings.4 params
Move a node to a different parent in a scene and optionally control its position among siblings.
Parameters* required
node_path*stringPath to the node to move
scene_path*stringPath to the scene file
sibling_indexnumberOptional position among siblings (0 = first child). Omit or -1 to append.
new_parent_path*stringPath to the new parent node (. for root)
attach_scriptAttach or change a script on a node in a scene.3 params
Attach or change a script on a node in a scene.
Parameters* required
node_pathstringPath to the node (. for root, or relative path)
scene_path*stringPath to the scene file
script_path*stringPath to the script file (res://path/to/script.gd)
detach_scriptRemove a script from a node in a scene.2 params
Remove a script from a node in a scene.
Parameters* required
node_path*stringPath to the node (. for root)
scene_path*stringPath to the scene file
set_collision_shapeCreate and assign a collision shape resource to a CollisionShape2D or CollisionShape3D node. Supports: CircleShape2D, RectangleShape2D, CapsuleShape2D, SphereShape3D, BoxShape3D, etc.4 params
Create and assign a collision shape resource to a CollisionShape2D or CollisionShape3D node. Supports: CircleShape2D, RectangleShape2D, CapsuleShape2D, SphereShape3D, BoxShape3D, etc.
Parameters* required
node_pathstringPath to the CollisionShape2D/3D node
scene_path*stringPath to the .tscn scene file
shape_type*stringShape type: CircleShape2D, RectangleShape2D, CapsuleShape2D, SphereShape3D, BoxShape3D, etc.
shape_paramsobjectShape parameters: {radius: 32} for circles, {size: {x: 64, y: 64}} for rectangles, etc.
set_sprite_textureAssign 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 aft...4 params
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 aft...
Parameters* required
node_pathstringPath to the Sprite2D/Sprite3D/TextureRect node
scene_path*stringPath to the .tscn scene file
texture_type*stringHow to obtain the texture. Prefer FromPath for assets on disk.one of
FromPath · ImageTexture · NewImageTexture · PlaceholderTexture2D · GradientTexture2D · NoiseTexture2Dtexture_paramsobjectTexture parameters. FromPath / ImageTexture / NewImageTexture: {path: "res://assets/sprite.png"}. PlaceholderTexture2D: {size: {x: 64, y: 64}}. GradientTexture2D / NoiseTexture2D: {width, height}.
instance_sceneAdd 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.5 params
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.
Parameters* required
node_namestringOptional name for the instance. If omitted, uses the instanced scene's root node name.
propertiesobjectOptional property overrides on the instance root (e.g., {position: {type: "Vector3", x: 5, y: 0, z: 10}})
scene_path*stringPath to the scene file being edited (the parent scene)
parent_pathstringPath to parent node within the scene (. for root, or relative path like Level/Enemies)
instance_path*stringPath to the .tscn scene to instance (the child/prefab scene)
set_meshCreate 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.4 params
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.
Parameters* required
mesh_type*stringMesh class: "BoxMesh", "SphereMesh", "CylinderMesh", "CapsuleMesh", "PlaneMesh", "PrismMesh", "TorusMesh", "QuadMesh", "TextMesh", or "file" to load from a resource path
node_pathstringPath to the MeshInstance3D node within the scene
scene_path*stringPath to the .tscn scene file
mesh_paramsobjectBoxMesh: {size:{x,y,z}}. SphereMesh: {radius,height,radial_segments,rings}. CylinderMesh: {top_radius,bottom_radius,height}. CapsuleMesh: {radius,height}. PlaneMesh: {size:{x,y}}. PrismMesh: {left_to_right,size:{x,y,z}}. TorusMesh: {inner_radius,outer_radius,rings}. QuadMesh: {size:{x,y}}. TextMesh: {text,font_size,depth}. file: {path:"res://mesh.tres"}
set_materialCreate and assign a material to a MeshInstance3D, CSG, or GeometryInstance3D node. Supports StandardMaterial3D or loading from file.5 params
Create and assign a material to a MeshInstance3D, CSG, or GeometryInstance3D node. Supports StandardMaterial3D or loading from file.
Parameters* required
node_pathstringPath to the target node
scene_path*stringPath to the .tscn scene file
material_type*string"StandardMaterial3D" or "file" to load from a resource path
surface_indexnumberFor MeshInstance3D only: surface index for per-surface override. Omit for material_override on all surfaces.
material_paramsobjectStandardMaterial3D: {albedo_color:{r,g,b,a}, metallic:0-1, roughness:0-1, emission:{r,g,b}, emission_energy:float, transparency:0=disabled/1=alpha/2=scissor/3=hash/4=depth_pre_pass}. file: {path:"res://material.tres"}
get_node_spatial_infoQuery 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.3 params
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.
Parameters* required
node_pathstringPath to the Node3D (. for root, or relative path like Level/Props/Crate)
scene_path*stringPath to the .tscn scene file
include_boundsbooleanInclude computed subtree AABBs when visual descendants exist (default: true)
measure_node_distanceMeasure the world-space distance between two Node3D nodes in a scene file. Returns both the full 3D delta and the horizontal XZ distance.3 params
Measure the world-space distance between two Node3D nodes in a scene file. Returns both the full 3D delta and the horizontal XZ distance.
Parameters* required
scene_path*stringPath to the .tscn scene file
to_node_path*stringPath to the second Node3D
from_node_path*stringPath to the first Node3D
snap_node_to_gridSnap a Node3D position to a grid in local or global space. Useful for modular level building and keeping 3D scenes aligned.5 params
Snap a Node3D position to a grid in local or global space. Useful for modular level building and keeping 3D scenes aligned.
Parameters* required
axesarrayAxes to snap. Any of: ["x"], ["x","z"], ["x","y","z"] (default: all axes)
spacestringCoordinate space: "local" or "global" (default: "global")
grid_size*valuePositive grid size. Use a number for uniform snapping or {x,y,z} for per-axis snapping.
node_pathstringPath to the Node3D to snap
scene_path*stringPath to the .tscn scene file
set_node_propertiesSet 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_pro...3 params
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_pro...
Parameters* required
node_pathstringPath to the node (. for root, or relative path)
properties*objectMap of property_name -> value. Each value follows the same form as modify_node_property.value (primitives, arrays, or {type:"Vector3",...} discriminated objects).
scene_path*stringPath to the .tscn scene file
set_node_groupsSet, 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).4 params
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).
Parameters* required
modestringreplace (default): node ends up in EXACTLY the listed groups. add: union with existing. remove: drop the listed groups.one of
replace · add · removegroups*arrayList of group names to apply
node_pathstringPath to the node (. for root)
scene_path*stringPath to the .tscn scene file
get_node_groupsRead the list of groups a node belongs to in a .tscn scene file.2 params
Read the list of groups a node belongs to in a .tscn scene file.
Parameters* required
node_pathstringscene_path*stringfind_nodes_in_groupFind 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().2 params
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().
Parameters* required
group*stringGroup name to search for
scene_path*stringset_resource_propertyModify 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...5 params
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...
Parameters* required
value*valueNew value (same shape as modify_node_property.value)
node_pathstringPath to the node owning the resource
scene_path*stringPath to the .tscn scene file
property_name*stringProperty on the target resource to set (e.g. "radius", "albedo_color")
resource_path*stringPath from node to the target resource via property names. Examples: "shape", "material", "material/next_pass"
save_resource_to_fileSave 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 th...4 params
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 th...
Parameters* required
save_to*stringDestination path (res://.../foo.tres)
node_pathstringscene_path*stringresource_path*stringPath from node to the resource (e.g. "shape", "material")
get_resource_infoInspect 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 s...4 params
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 s...
Parameters* required
pathstringPath mode: resource path on disk (res://...).
node_pathstringNode mode: path to the node within the scene.
scene_pathstringNode mode: path to the .tscn that owns the node.
resource_propertystringNode mode: property name on the node holding the resource (e.g. "shape", "material", "stream", "texture").
list_signal_connectionsList 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 c...5 params
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 c...
Parameters* required
sourcestringWhere to read connections from. Default: scene_fileone of
scene_file · runtimenode_path*stringPath to the node. For source="runtime" use absolute (/root/Main/Player) or relative to current_scene.
scene_pathstringFor source="scene_file": path to the .tscn
include_incomingbooleanInclude signals from other nodes whose handler is on this node (default: true). Only honored for scene_file source.
include_outgoingbooleanInclude signals that this node emits (default: true)
connect_signalConnect 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 atta...6 params
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 atta...
Parameters* required
flagsnumberConnection flags (CONNECT_DEFERRED=1, CONNECT_PERSIST=2, CONNECT_ONE_SHOT=4). Default 0.
method*stringMethod name on the receiving node's script
signal*stringSignal name on the emitting node
to_node*stringPath to the receiving node
from_node*stringPath to the emitting node
scene_path*stringdisconnect_signalRemove a signal connection from a .tscn scene file. No-op if the connection doesn't exist.5 params
Remove a signal connection from a .tscn scene file. No-op if the connection doesn't exist.
Parameters* required
method*stringsignal*stringto_node*stringfrom_node*stringscene_path*stringedit_scriptApply 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 ru...1 params
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 ru...
Parameters* required
edit*objectEdit spec: {type: "snippet_replace", file: "res://path.gd", old_snippet: "old code", new_snippet: "new code", context_before: "line above", context_after: "line below"}. Keep old_snippet SMALL (1-10 lines).
validate_scriptValidate a GDScript file for syntax errors using Godot's built-in parser. Call after creating or modifying scripts to ensure they are error-free.1 params
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.
Parameters* required
path*stringPath to the GDScript file to validate (e.g., res://scripts/player.gd)
create_folderCreate a directory (with parent directories if needed).1 params
Create a directory (with parent directories if needed).
Parameters* required
path*stringDirectory path (res://path/to/folder)
delete_filePermanently 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 (an...4 params
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 (an...
Parameters* required
path*stringPath to the file to delete (e.g. res://scenes/old.tscn)
forcebooleanIf true, bypass the "file is open in editor" guard. Use ONLY if you know the file is not the active scene. The guard exists because deleting the active scene tab from under the editor can crash Godot.
confirm*booleanREQUIRED. Must be explicitly set to true — safety gate to prevent accidental deletes. Calls without confirm=true fail with an error.
create_backupbooleanIf true (default), saves a .bak copy next to the original before deletion so the file can be recovered. Set false to delete without backup.
rename_fileRename or move a file, optionally updating references in other files.3 params
Rename or move a file, optionally updating references in other files.
Parameters* required
new_path*stringNew file path
old_path*stringCurrent file path
update_referencesbooleanUpdate references in other files (default: true)
list_scriptsList all GDScript files in the project with basic metadata.
List all GDScript files in the project with basic metadata.
No parameters — call it with no arguments.
get_project_settingsConcise project settings summary: main_scene, window size/stretch, physics tick rate, and render basics.2 params
Concise project settings summary: main_scene, window size/stretch, physics tick rate, and render basics.
Parameters* required
include_renderbooleanInclude render settings
include_physicsbooleanInclude physics settings
get_input_mapReturn 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 curr...1 params
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 curr...
Parameters* required
include_deadzonesbooleanInclude the per-action "deadzone" field in each action object (default: true). When true, each action is {"deadzone": 0.5, "events": [...]}. When false, each action is {"events": [...]}.
get_collision_layersReturn named 2D/3D physics collision layers from ProjectSettings.
Return named 2D/3D physics collision layers from ProjectSettings.
No parameters — call it with no arguments.
get_node_propertiesGet 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).1 params
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).
Parameters* required
node_type*stringNode class name (e.g., "Sprite2D", "Control", "Label", "Button")
get_console_logReturn the latest lines from the Godot editor output log.1 params
Return the latest lines from the Godot editor output log.
Parameters* required
max_linesnumberMaximum number of lines to include (default: 50)
get_errorsGet 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...2 params
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...
Parameters* required
max_errorsnumberMaximum number of errors to return (default: 50)
include_warningsbooleanInclude warnings in addition to errors (default: true)
clear_console_logMark the current position in the Godot editor log. Subsequent get_console_log and get_errors calls will only return output after this point.
Mark the current position in the Godot editor log. Subsequent get_console_log and get_errors calls will only return output after this point.
No parameters — call it with no arguments.
open_in_godotOpen a file in the Godot editor at a specific line (side-effect only).2 params
Open a file in the Godot editor at a specific line (side-effect only).
Parameters* required
linenumber1-based line number
path*stringres:// path to open
scene_tree_dumpDump the scene tree of the scene currently open in the Godot editor (node names, types, and attached scripts).
Dump the scene tree of the scene currently open in the Godot editor (node names, types, and attached scripts).
No parameters — call it with no arguments.
list_settingsBrowse 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 wit...1 params
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 wit...
Parameters* required
categorystringSettings category prefix (e.g., "display", "physics", "rendering", "application", "audio"). Omit to list all available categories.
update_project_settingsUpdate 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 p...1 params
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 p...
Parameters* required
settings*objectDictionary of setting paths to new values (e.g., {"display/window/size/viewport_width": 1920, "display/window/size/viewport_height": 1080})
configure_input_mapAdd, remove, or replace input actions and their key/button bindings. Use get_input_map to see current actions before modifying.4 params
Add, remove, or replace input actions and their key/button bindings. Use get_input_map to see current actions before modifying.
Parameters* required
action*stringInput action name (e.g., "move_left", "jump", "attack")
eventsarrayInput events to bind. Each object needs a "type" field: {"type":"key","key":"Space"} for keyboard, {"type":"mouse_button","button_index":1} for mouse (1=left,2=right,3=middle), {"type":"joypad_button","button_index":0} for gamepad, {"type":"joypad_motion","axis":0,"axis_value":1.0} for gamepad axis.
deadzonenumberAction deadzone (default: 0.5)
operation*string"add" to create action and/or append events, "remove" to delete the action entirely, "set" to replace all events on an action (creates it if needed)
run_sceneLaunch 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, sce...4 params
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, sce...
Parameters* required
scenestringScene to run: omit for main scene, "current" for the currently open scene, or a res:// path for a specific scene
wait_for_runtimebooleanWait until the MCPRuntime in-game helper connects back (required for take_screenshot/send_input). Default: false.
startup_timeout_msnumberMax time in ms to wait for the above signals. Default: 10000. Bump to 15000–20000 on slower machines or autoload-heavy projects.
block_until_startedbooleanWait until the editor reports playing=true before returning (default: true). Up to startup_timeout_ms.
stop_sceneStop the currently running scene in the Godot editor. Always stop the scene before editing code to avoid errors repeating every frame.
Stop the currently running scene in the Godot editor. Always stop the scene before editing code to avoid errors repeating every frame.
No parameters — call it with no arguments.
is_playingCompatibility shim: returns {playing, scene}. For richer info (uptime, runtime helper connectivity, last-launched target) prefer get_runtime_status.
Compatibility shim: returns {playing, scene}. For richer info (uptime, runtime helper connectivity, last-launched target) prefer get_runtime_status.
No parameters — call it with no arguments.
get_runtime_statusCombined 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).
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).
No parameters — call it with no arguments.
waitSleep 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).2 params
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).
Parameters* required
msnumberMilliseconds to wait (1..30000).
secondsnumberSeconds to wait (0.001..30). Convenient when the agent is thinking in seconds.
take_screenshotCapture 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...2 params
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...
Parameters* required
save_tostringOptional res:// or user:// destination path. Defaults to res://addons/godot_mcp/cache/screenshots/screenshot_<ms>.png
return_base64booleanAlso include the PNG bytes inline as base64 (default: false). Useful when the agent has no filesystem access.
send_inputSynthesize 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, alte...1 params
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, alte...
Parameters* required
event*objectInputEvent descriptor:
Key: {type:"key", key:"Space", pressed:true, shift?:bool, ctrl?:bool, alt?:bool} or {type:"key", keycode:32, pressed:true}
Mouse button: {type:"mouse_button", button_index:1, pressed:true, position:{x,y}, double_click?:bool} (1=left, 2=right, 3=middle)
Mouse motion: {type:"mouse_motion", position:{x,y}, relative?:{x,y}}
Action (named input from the InputMap): {type:"action", action:"jump", pressed:true, strength?:1.0}
query_runtime_nodeQuery 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 `prope...4 params
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 `prope...
Parameters* required
node_path*stringAbsolute path (e.g. /root/Main/Player) or relative to current_scene.
propertiesarrayProperty names to read. Default: position, global_position, rotation, scale, visible, modulate.
include_groupsbooleanInclude the node's group memberships. Default: true.
include_childrenbooleanList direct children {name, class}. Default: false.
get_runtime_logReturn 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 — th...2 params
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 — th...
Parameters* required
limitnumberMaximum entries to return (default: 200, max 500)
since_msnumberOnly return entries with ts_ms >= since_ms. Use 0 (default) for all.
classdb_queryQuery 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 incorre...3 params
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 incorre...
Parameters* required
querystringWhat to return: "all" (default), "properties", "methods", or "signals"
class_name*stringGodot class name to query (e.g., "CharacterBody2D", "Sprite2D", "Control")
include_virtualbooleanInclude well-known virtual methods like _ready, _process, _input (default: true). Set to false to see only public non-virtual methods.
rescan_filesystemTrigger 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.
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.
No parameters — call it with no arguments.
setup_autoloadRegister, unregister, or list autoload singletons. Autoloads are scripts/scenes loaded automatically at project start.3 params
Register, unregister, or list autoload singletons. Autoloads are scripts/scenes loaded automatically at project start.
Parameters* required
namestringAutoload name (e.g., "GameManager", "AudioManager")
pathstringres:// path to the script or scene file (required for "add")
operation*string"add" to register, "remove" to unregister, "list" to show all autoloads
generate_2d_assetRender 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...6 params
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...
Parameters* required
scalenumberOptional explicit render scale (e.g. 2.0 = 2x). Overrides width/height-derived scaling. Default: 1.0.
widthnumberOptional desired output width in pixels. Combined with the SVG's intrinsic width to derive a uniform render_scale.
heightnumberOptional desired output height in pixels. Same as width but matched on the height axis. If both width and height are provided, width takes precedence for scale derivation.
filename*stringOutput filename. ".png" appended if missing.
svg_code*stringComplete SVG markup. Either single or double quotes are accepted in attributes.
save_pathstringDestination directory (default: res://assets/generated/). Created if it does not exist.
map_projectCrawl 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.2 params
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.
Parameters* required
rootstringRoot path to start crawling from (default: res://)
include_addonsbooleanWhether to include scripts in the addons/ folder (default: false)
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 · 42 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.
Then go to Project → Project Settings → Plugins and enable the Godot MCP plugin.
2. Add the server config to your AI client
Claude Desktop — Settings → Developer → Edit Config → open the config file and paste:
Mac / Linux:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
Windows:
{
"mcpServers": {
"godot": {
"command": "cmd",
"args": ["/c", "npx", "-y", "godot-mcp-server"]
}
}
}
Cursor — Settings → MCP → Add Server:
Mac / Linux:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
Windows:
{
"mcpServers": {
"godot": {
"command": "cmd",
"args": ["/c", "npx", "-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?
42 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 | 14 | Run/stop scenes, query ClassDB, read errors from Output + Debugger, project settings, input map, collision layers, scene tree dumps, rescan filesystem |
| Asset Generation | 1 | Generate 2D sprites from SVG |
| Visualization | 6 | Interactive browser-based project map, scene graph explorer |
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 │ │ 42 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)
- 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.
Release notes
Narrative write-ups of each release live in release-notes/ (starting with v0.5.0). For the full change history, see CHANGELOG.md.
License
MIT
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
Packagegodot-mcp-server
TransportSTDIO
Resources5
Tools verifiedJun 11, 2026
UpdatedApr 21, 2026
