godot_add_node
Add a new node to an existing Godot scene by specifying the node type, scene path, and parent location within the project.
Instructions
Add a new node of any instantiable Godot node type to an existing saved scene.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes | Path to the Godot project directory or its project.godot file. | |
| scene_path | Yes | Path to the target .tscn file. Absolute, relative, and res:// paths are supported. | |
| node_type | Yes | Godot node class to instantiate, such as Sprite2D, Timer, Control, or AudioStreamPlayer2D. | |
| parent_path | No | Scene-relative node path where the new node should be attached. Use '.' for the root. | . |
| node_name | No | Optional explicit node name. Defaults to the chosen node type. | |
| godot_executable | No | Optional explicit path to the Godot executable or .app bundle. |
Implementation Reference
- src/godot_mcp/godot.py:1239-1290 (handler)The implementation of the 'add_node' method in the GodotController class, which runs a helper script 'add_node.gd'.
def add_node( self, project_path: str, scene_path: str, node_type: str, parent_path: str = ".", node_name: str | None = None, godot_executable: str | None = None, ) -> dict[str, Any]: project_dir = ensure_project_path(project_path) executable, version = resolve_godot_executable(godot_executable) absolute_scene_path, resource_scene_path = resolve_scene_path(project_dir, scene_path) if not absolute_scene_path.exists(): raise GodotError(f"Scene not found: {absolute_scene_path}") final_node_type = node_type.strip() if not final_node_type: raise GodotError("`node_type` is required.") final_node_name = (node_name or "").strip() or final_node_type normalized_parent_path = normalize_scene_node_path(parent_path) output = _run_godot_script( executable=executable, project_dir=project_dir, script_name="add_node.gd", user_args=[ "--scene-path", resource_scene_path, "--parent-path", normalized_parent_path, "--node-type", final_node_type, "--node-name", final_node_name, ], ) parsed = _parse_script_json_output(output, "add_node.gd") return { "project_path": str(project_dir), "scene_path": str(absolute_scene_path), "scene_resource_path": resource_scene_path, "parent_path": parsed.get("parent_path", normalized_parent_path), "node_path": parsed.get("node_path"), "node_name": parsed.get("node_name", final_node_name), "node_type": parsed.get("node_type", final_node_type), "godot_executable": str(executable), "godot_version": version, } - src/godot_mcp/server.py:503-545 (registration)The registration of the 'godot_add_node' tool within the GodotMcpServer class, mapping it to the controller method.
name="godot_add_node", description="Add a new node of any instantiable Godot node type to an existing saved scene.", input_schema={ "type": "object", "properties": { "project_path": { "type": "string", "description": "Path to the Godot project directory or its project.godot file.", }, "scene_path": { "type": "string", "description": "Path to the target .tscn file. Absolute, relative, and res:// paths are supported.", }, "node_type": { "type": "string", "description": "Godot node class to instantiate, such as Sprite2D, Timer, Control, or AudioStreamPlayer2D.", }, "parent_path": { "type": "string", "description": "Scene-relative node path where the new node should be attached. Use '.' for the root.", "default": ".", }, "node_name": { "type": "string", "description": "Optional explicit node name. Defaults to the chosen node type.", }, "godot_executable": { "type": "string", "description": "Optional explicit path to the Godot executable or .app bundle.", }, }, "required": ["project_path", "scene_path", "node_type"], "additionalProperties": False, }, handler=lambda args: self.controller.add_node( project_path=args["project_path"], scene_path=args["scene_path"], node_type=args["node_type"], parent_path=args.get("parent_path", "."), node_name=args.get("node_name"), godot_executable=args.get("godot_executable"), ), ),