Godot MCP

Instructions

Implementation Reference

• src/godot_mcp/godot.py:1175-1237 (handler)

  Implementation of the get_scene_tree logic.

  def get_scene_tree(
      self,
      project_path: str,
      scene_path: str,
      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}")
  
      output = _run_godot_script(
          executable=executable,
          project_dir=project_dir,
          script_name="inspect_scene.gd",
          user_args=["--scene-path", resource_scene_path],
      )
      parsed = _parse_script_json_output(output, "inspect_scene.gd")
      nodes = parsed.get("nodes")
      connections = parsed.get("connections", [])
      if not isinstance(nodes, list):
          raise GodotError("Scene inspection did not return a node list.")
      if not isinstance(connections, list):
          raise GodotError("Scene inspection did not return a connection list.")
  
      normalized_nodes: list[dict[str, Any]] = []
      for node in nodes:
          if not isinstance(node, dict):
              continue
          normalized_node = dict(node)
          normalized_node["path"] = canonical_scene_node_path(str(node.get("path", ".")), ".")
          normalized_node["parent_path"] = canonical_scene_node_path(str(node.get("parent_path", "")), "")
          normalized_node["owner_path"] = canonical_scene_node_path(str(node.get("owner_path", "")), "")
          normalized_nodes.append(normalized_node)
  
      normalized_connections: list[dict[str, Any]] = []
      for connection in connections:
          if not isinstance(connection, dict):
              continue
          normalized_connection = dict(connection)
          normalized_connection["source_path"] = canonical_scene_node_path(
              str(connection.get("source_path", "")),
              "",
          )
          normalized_connection["target_path"] = canonical_scene_node_path(
              str(connection.get("target_path", "")),
              "",
          )
          normalized_connections.append(normalized_connection)
  
      return {
          "project_path": str(project_dir),
          "scene_path": str(absolute_scene_path),
          "scene_resource_path": resource_scene_path,
          "node_count": len(normalized_nodes),
          "nodes": normalized_nodes,
          "scene_tree": _build_scene_tree(normalized_nodes),
          "connections": normalized_connections,
          "godot_executable": str(executable),
          "godot_version": version,
      }

• src/godot_mcp/server.py:447-473 (registration)

  Registration of the godot_get_scene_tree tool in the server.

      name="godot_get_scene_tree",
      description="Inspect a saved scene and return its node hierarchy plus parent/child relationships.",
      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.",
              },
              "godot_executable": {
                  "type": "string",
                  "description": "Optional explicit path to the Godot executable or .app bundle.",
              },
          },
          "required": ["project_path", "scene_path"],
          "additionalProperties": False,
      },
      handler=lambda args: self.controller.get_scene_tree(
          project_path=args["project_path"],
          scene_path=args["scene_path"],
          godot_executable=args.get("godot_executable"),
      ),
  ),