run_project
Start a Godot runtime session, spawned or attached to a game you launch, so you can take screenshots, simulate input, inspect UI and run scripts. Required before any in-game interaction.
Instructions
Start a runtime session: spawn the project (stdout/stderr captured; asks the user to confirm the first time per project), or with attach: true wait for a Godot you launch yourself (nothing spawned or captured). Required before take_screenshot, simulate_input, get_ui_elements and run_script; returns once the bridge answers. It becomes current; others keep running. Returns: projectPath, sessionMode, bridgePort, message; warnings leads on a start caveat. Errors if the bridge never answers.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectPath": "<projectPath>"
},
"name": "run_project"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scene | No | Scene to run (path relative to project, e.g. "scenes/main.tscn"). Omit to use the project's main scene. Not valid with attach: true. Must end in .tscn, .scn, .escn, .tres or .res. | |
| attach | No | If true, do not spawn Godot: inject the bridge and wait for a Godot process you launch yourself (up to 20s for it to start listening, 45s total once it has). Call before Godot launches, or start the launch in parallel, because Godot reads autoloads only at startup. One attach session per project; attaching again keeps this server's attached session unless its bridge is gone, and says so in warnings. Cannot be combined with scene, background or profiling. Nothing is captured: get_debug_output returns null logs with a warning, and the profiler is unavailable. | |
| profiling | No | Attach Godot's own remote debugger so profile_project, start_profiler and stop_profiler can measure this session. Must be set at launch - a session already running cannot be profiled - and costs a little runtime overhead. Not valid with attach: true. | |
| background | No | If true, the game window is never shown on Windows and is moved off-screen after startup on other platforms; mouse input passes through to whatever is beneath it. Programmatic input (simulate_input, run_script) and screenshots stay fully active. It does not guarantee the game never takes keyboard focus. Not valid with attach: true. | |
| bridgePort | No | TCP port for the MCP bridge. Omit to auto-select a free port (recommended). Spawned sessions receive it through an environment variable; attach mode bakes it into the injected bridge script, so the Godot you launch listens on exactly this port. A port held by a live session on another project is refused. | |
| projectPath | Yes | Path to the Godot project directory |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| warnings | No | ||
| bridgePort | Yes | ||
| projectPath | Yes | ||
| sessionMode | Yes |