Godot MCP

Instructions

Implementation Reference

• src/godot_mcp/server.py:857-889 (handler)

  Registration of the `godot_run_scene` tool, which delegates to `GodotController.run_scene`.

      name="godot_run_scene",
      description="Run a specific Godot scene from an existing project.",
      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.",
              },
              "headless": {
                  "type": "boolean",
                  "description": "Whether to run the scene in headless mode.",
                  "default": False,
              },
              "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.run_scene(
          project_path=args["project_path"],
          scene_path=args["scene_path"],
          headless=bool(args.get("headless", False)),
          godot_executable=args.get("godot_executable"),
      ),
  ),

• src/godot_mcp/godot.py:2058-2087 (handler)

  The `GodotController.run_scene` method that implements the tool's execution logic by launching a Godot subprocess.

  def run_scene(
      self,
      project_path: str,
      scene_path: str,
      godot_executable: str | None = None,
      headless: bool = False,
  ) -> 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}")
  
      command = [str(executable), "--path", str(project_dir)]
      if headless:
          command.append("--headless")
      command.append(str(absolute_scene_path))
  
      launched = _launch_process(command, cwd=project_dir, log_name="run-scene")
      return {
          "project_path": str(project_dir),
          "scene_path": str(absolute_scene_path),
          "scene_resource_path": resource_scene_path,
          "pid": launched.pid,
          "command": launched.command,
          "log_path": launched.log_path,
          "headless": headless,
          "godot_version": version,
      }