Godot MCP Server

Returns all scenes currently open in the Godot editor, including the active scene.

Returns: Array of scene objects: { path: string, root_node: string, root_type: string, node_count: number }

Examples:

• Use when: "What scenes are open?" or "List all scenes"

Returns the full node hierarchy of the specified scene (or the currently active scene if no path given).

Args:

• scene_path (string, optional): Path to the scene file e.g. "res://levels/main.tscn". Defaults to the active scene.

• depth (number, optional): Maximum recursion depth (default: 10, max: 50).

Returns: Nested node tree: { name, type, path, children[], properties? }

Examples:

• Use when: "Show me the scene tree" or "What nodes are in res://player.tscn?"

Returns all properties of a specific node by its scene path.

Args:

• node_path (string): Full node path e.g. "/root/Main/Player" or "Player/Sprite2D"

• scene_path (string, optional): Scene to look in. Defaults to active scene.

Returns: { name, type, path, properties: Record<string, unknown> }

Examples:

• Use when: "What are the properties of the Player node?"

• Use when: "Get transform of res://enemy.tscn root node"

Adds a new node of the specified type as a child of the given parent node.

Args:

• parent_path (string): Node path of the parent e.g. "/root/Main"

• node_type (string): Godot class name e.g. "Sprite2D", "CharacterBody2D", "Label", "AudioStreamPlayer"

• node_name (string): Name for the new node

• scene_path (string, optional): Scene to modify. Defaults to active scene.

• properties (object, optional): Initial property values to set on the new node.

Returns: { name, type, path } of the created node.

Examples:

• Use when: "Add a Sprite2D called PlayerSprite under /root/Main"

• Use when: "Add a Label node to the HUD with text 'Score: 0'"

Removes a node (and all its children) from the scene. This is destructive and cannot be undone via MCP.

Args:

• node_path (string): Full node path to remove e.g. "/root/Main/OldEnemy"

• scene_path (string, optional): Scene to modify. Defaults to active scene.

Returns: Confirmation message.

Sets one or more properties on an existing node.

Args:

• node_path (string): Full node path e.g. "/root/Main/Player"

• properties (object): Key/value pairs to set. Values must be JSON-serialisable Godot variants. Common keys: "position", "rotation", "scale", "visible", "modulate", "text", "texture"

• scene_path (string, optional): Scene to modify. Defaults to active scene.

Returns: Updated property values.

Examples:

• Use when: "Move the Player to position (100, 200)" -> properties: { "position": {"x": 100, "y": 200} }

• Use when: "Hide the HUD node" -> properties: { "visible": false }

Moves a node to a new parent within the same scene, preserving its world transform.

Args:

• node_path (string): Node to move e.g. "/root/Main/Enemy"

• new_parent_path (string): Destination parent e.g. "/root/Main/EnemyGroup"

• scene_path (string, optional): Scene to modify. Defaults to active scene.

• keep_global_transform (boolean, optional): Whether to preserve world-space transform (default: true)

Returns: New node path after reparenting.

Instantiates an existing .tscn file as a child node inside another scene.

Args:

• scene_to_instantiate (string): res:// path of the scene to instance e.g. "res://enemies/goblin.tscn"

• parent_path (string): Node path of the parent in the target scene e.g. "/root/Main"

• node_name (string, optional): Override the instance name. Defaults to the scene file's stem.

• target_scene_path (string, optional): Scene that will receive the instance. Defaults to active scene.

• properties (object, optional): Properties to override on the root node of the instance.

Returns: { name, type, path } of the instantiated node.

Examples:

• Use when: "Add a Goblin enemy to the level at position (300, 100)" -> scene_to_instantiate: "res://enemies/goblin.tscn", parent_path: "/root/Level" properties: { "position": {"x": 300, "y": 100} }

Saves the specified scene (or active scene) to disk.

Args:

• scene_path (string, optional): res:// path of the scene to save. Omit for active scene.

• save_as (string, optional): New res:// path to save a copy to (like Save As).

Returns: Confirmation with the saved path.

Reads the content of a GDScript (.gd) or other text-based resource file.

Args:

• file_path (string): res:// path e.g. "res://player/player.gd"

Returns: { path: string, content: string }

Writes (creates or overwrites) a GDScript file at the given path.

Args:

• file_path (string): res:// path e.g. "res://player/player.gd"

• content (string): Full GDScript source code to write.

Returns: Confirmation with the file path.

Examples:

• Use when: "Create a new movement script for the Player"

Executes a GDScript expression or block in the Godot editor context (via EditorScript). Useful for querying engine state or performing quick operations.

Args:

• code (string): GDScript code to execute. Should be a valid expression or a series of statements. Has access to: Engine, ProjectSettings, EditorInterface (in editor context).

• timeout_ms (number, optional): Max execution time in milliseconds (default: 5000, max: 30000).

Returns: { success: boolean, output: string, error?: string }

Examples:

• Use when: "What is the current project name?" -> code: "ProjectSettings.get_setting('application/config/name')"

• Use when: "List all files in res://levels/" -> code: "DirAccess.get_files_at('res://levels/')"

Warning: This runs arbitrary code in the editor. Use with care.

Lists files in the Godot project filesystem under a given directory.

Args:

• directory (string, optional): res:// directory path (default: "res://")

• filter_type (string, optional): Filter by extension e.g. "tscn", "gd", "png", "tres". Omit for all.

• recursive (boolean, optional): Include subdirectories (default: false)

• limit (number, optional): Max results (default: 50, max: 200)

• offset (number, optional): Pagination offset (default: 0)

Returns: { total, count, offset, has_more, items: [{ path, type, name }] }

Returns metadata about a specific resource file (texture, audio, mesh, etc.).

Args:

• resource_path (string): res:// path to the resource e.g. "res://assets/player.png"

Returns: { path, type, name, metadata: object }

Loads a resource and assigns it to a property of a node. Useful for setting textures, materials, audio streams, etc.

Args:

• node_path (string): Node path e.g. "/root/Main/Player/Sprite2D"

• property (string): Property name e.g. "texture", "material", "stream"

• resource_path (string): res:// path to the resource to assign

• scene_path (string, optional): Scene to modify. Defaults to active scene.

Returns: Confirmation of the assignment.

Examples:

• Use when: "Set the player sprite texture to res://assets/player.png" -> node_path: "/root/Main/Player/Sprite2D", property: "texture", resource_path: "res://assets/player.png"

Creates a new empty scene file (.tscn) with a specified root node type.

Args:

• scene_path (string): res:// path for the new scene e.g. "res://levels/level2.tscn"

• root_type (string): Godot class for the root node e.g. "Node2D", "Node3D", "Control", "CharacterBody2D"

• root_name (string, optional): Name for the root node (defaults to the scene file stem)

• open_in_editor (boolean, optional): Open the new scene in the editor (default: true)

Returns: { path, root_node, root_type } of the created scene.