Godot MCP

Instructions

Implementation Reference

• src/godot_mcp/godot.py:2202-2278 (handler)

  Implementation of the run_with_capture tool logic in the GodotController class.

  def run_with_capture(
      self,
      project_path: str,
      scene_path: str | None = None,
      godot_executable: str | None = None,
      headless: bool = False,
      capture_seconds: float = 3.0,
      max_output_chars: int = 12000,
  ) -> dict[str, Any]:
      project_dir = ensure_project_path(project_path)
      executable, version = resolve_godot_executable(godot_executable)
      if capture_seconds <= 0:
          raise GodotError("`capture_seconds` must be greater than 0.")
  
      command = [str(executable), "--log-file", str(_create_log_path(project_dir, "run-capture")), "--path", str(project_dir)]
      absolute_scene_path: Path | None = None
      resource_scene_path: str | None = None
      run_target = "project"
      if headless:
          command.append("--headless")
      if scene_path:
          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.append(str(absolute_scene_path))
          run_target = "scene"
  
      log_path = Path(command[2])
      process = subprocess.Popen(
          command,
          cwd=project_dir,
          stdout=subprocess.PIPE,
          stderr=subprocess.PIPE,
          text=True,
      )
  
      terminated_after_capture = False
      force_killed = False
      try:
          stdout_text, stderr_text = process.communicate(timeout=capture_seconds)
      except subprocess.TimeoutExpired:
          terminated_after_capture = True
          process.terminate()
          try:
              stdout_text, stderr_text = process.communicate(timeout=5)
          except subprocess.TimeoutExpired:
              force_killed = True
              process.kill()
              stdout_text, stderr_text = process.communicate(timeout=5)
  
      log_text = log_path.read_text(encoding="utf-8", errors="replace") if log_path.exists() else ""
      stdout_excerpt, stdout_truncated = _truncate_text(stdout_text, max_output_chars)
      stderr_excerpt, stderr_truncated = _truncate_text(stderr_text, max_output_chars)
      log_excerpt, log_truncated = _truncate_text(log_text, max_output_chars)
      debug_output = _classify_debug_lines(stdout_text, stderr_text, log_text)
  
      return {
          "project_path": str(project_dir),
          "scene_path": str(absolute_scene_path) if absolute_scene_path is not None else None,
          "scene_resource_path": resource_scene_path,
          "run_target": run_target,
          "command": command,
          "log_path": str(log_path),
          "headless": headless,
          "capture_seconds": capture_seconds,
          "exit_code": process.returncode,
          "terminated_after_capture": terminated_after_capture,
          "force_killed": force_killed,
          "stdout": stdout_excerpt,
          "stderr": stderr_excerpt,
          "log_output": log_excerpt,
          "stdout_truncated": stdout_truncated,
          "stderr_truncated": stderr_truncated,
          "log_output_truncated": log_truncated,
          "debug_output": debug_output,
          "godot_version": version,
      }

• src/godot_mcp/server.py:891-936 (registration)

  Registration of the godot_run_with_capture tool in the MCP server.

      name="godot_run_with_capture",
      description="Run a Godot project or a specific scene for a short capture window and return stdout, stderr, log output, plus parsed warnings and errors.",
      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": "Optional scene to run instead of the project's configured main scene.",
              },
              "headless": {
                  "type": "boolean",
                  "description": "Whether to run in headless mode during capture.",
                  "default": False,
              },
              "capture_seconds": {
                  "type": "number",
                  "description": "How long to let the project or scene run before stopping it and collecting output.",
                  "default": 3.0,
              },
              "max_output_chars": {
                  "type": "integer",
                  "description": "Maximum number of characters to return for stdout, stderr, and log output excerpts.",
                  "default": 12000,
                  "minimum": 1,
              },
              "godot_executable": {
                  "type": "string",
                  "description": "Optional explicit path to the Godot executable or .app bundle.",
              },
          },
          "required": ["project_path"],
          "additionalProperties": False,
      },
      handler=lambda args: self.controller.run_with_capture(
          project_path=args["project_path"],
          scene_path=args.get("scene_path"),
          headless=bool(args.get("headless", False)),
          capture_seconds=float(args.get("capture_seconds", 3.0)),
          max_output_chars=int(args.get("max_output_chars", 12000)),
          godot_executable=args.get("godot_executable"),
      ),
  ),