godot_run_project

Launch a Godot project from its main scene, supporting headless mode and custom executable paths for development testing.

Instructions

Run a Godot project using its current main scene.

Input Schema

TableJSON Schema

Name	Required	Description
`project_path`	Yes	Path to the Godot project directory or its project.godot file.
`headless`	No	Whether to run the project in headless mode.
`godot_executable`	No	Optional explicit path to the Godot executable or .app bundle.

Implementation Reference

src/godot_mcp/godot.py:985-1006 (handler)

The handler function `run_project` implements the logic for running the Godot project. It validates the project path, resolves the Godot executable, constructs the command, and launches the process.

def run_project(
    self,
    project_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)

    command = [str(executable), "--path", str(project_dir)]
    if headless:
        command.append("--headless")

    launched = _launch_process(command, cwd=project_dir, log_name="run-project")
    return {
        "project_path": str(project_dir),
        "pid": launched.pid,
        "command": launched.command,
        "log_path": launched.log_path,
        "headless": headless,
        "godot_version": version,
    }

src/godot_mcp/server.py:212-239 (registration)

The tool `godot_run_project` is registered here with its input schema and handler mapping to `controller.run_project`.

    name="godot_run_project",
    description="Run a Godot project using its current main scene.",
    input_schema={
        "type": "object",
        "properties": {
            "project_path": {
                "type": "string",
                "description": "Path to the Godot project directory or its project.godot file.",
            },
            "headless": {
                "type": "boolean",
                "description": "Whether to run the project in headless mode.",
                "default": False,
            },
            "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_project(
        project_path=args["project_path"],
        headless=bool(args.get("headless", False)),
        godot_executable=args.get("godot_executable"),
    ),
),

Godot MCP