Start the game first
AI clientstdio →gui-mcpWebSocket →Game bridge→Gua adapter
The MCP server does not own UI state. The Godot application must start a bridge listening at ws://127.0.0.1:8765.
Register it with an MCP client
In a Bun environment, launch the published package with bunx. Adapt the following command and arguments to your client's configuration format.
{
"mcpServers": {
"gua": {
"command": "bunx",
"args": ["gui-mcp@latest", "mcp"],
"env": {
"GUA_BRIDGE_URL": "ws://127.0.0.1:8765"
}
}
}
}Available tools
get_ui_tree
Read the current screen and semantic UI tree. This is the normal first call.
click_node
Send a click request to a stable node ID.
wait_for_node
Wait for a node to appear or change state.
press_key
Send a key request, including to the currently focused element.
get_screenshot
Read the latest screenshot published by the runtime.
get_logs / run_test
Inspect runtime logs or invoke a runtime-side test operation.
Prompting an agent
Read the Gua UI tree and find the “Start Game” button.
Click it by stable ID, then wait until “Loading...” is visible.
If the operation fails, inspect the logs and report both
the relevant UI tree state and the likely cause.