English | 简体中文
Godot MCP server for AI-assisted game development. Run games, inspect state, and verify every change.
Wheel-mcp connects Codex, Cursor and other Model Context Protocol (MCP) clients to real Godot projects and game runtimes. Use it for GDScript debugging, runtime testing and AI-assisted game development: inspect scenes and runtime state, send inputs, read diagnostics, and verify changes with assertions, logs and screenshots.
Your assistant writes the code. Wheel-mcp runs the checks and returns evidence. Client setup adapters are available; form approval and end-to-end compatibility depend on the client version. See client compatibility.
Windows local stable · Godot 4.7.2 · MCP · MIT application code
Website · Quick start · Documentation · Latest download · Contributing
If this helps your Godot workflow, give it a Star. Bug reports, reproducible examples, and focused PRs are just as welcome.
Fewer tool exchanges. Leaner context. In a seven-case test, dev_loop reduced estimated payload tokens by 94.61% and MCP requests by 95.39% compared with a fine-grained workflow.
Use responseMode: "compact" for concise results and dev_loop to combine actions, assertions, and screenshots into one verification call.
Seven controlled cases on 2026-09-13; payload tokens estimated as JSON characters / 4, not billable tokens or runtime speedups.
With a real GODOT_PATH, npm run benchmark:comparison reproduces three alternating-order one-shot/persistent SDK query pairs. It records end-to-end time, engine starts, tool calls and serialized bytes, retaining every pair. Actual tokens, billing and whole-workflow efficiency are not measured; these results must not be mixed with the historical estimates above.
| Workflow | What the server provides |
|---|---|
| Explore a project | Scene, script, and resource discovery |
| Inspect a running game | Persistent runtime sessions and property inspection |
| Check behavior | Inputs, events, physics-frame waits, and explicit assertions |
| Diagnose failures | Engine diagnostics, runtime logs, and failure evidence |
| Verify a change | Screenshots, comparisons, and evidence artifacts |
The client plans and writes code; Wheel-mcp executes bounded Godot operations and reports evidence. This project is not an autonomous game generator, model provider, or replacement for your coding assistant.
The local stable release targets Windows, Godot 4.7.2 and trusted local projects over stdio. Each release includes the runtime package, SBOM, checksums and its source-bound acceptance receipt. The historical v0.2.0 receipt covers that frozen release, not later commits on main. See the local release scope. Long-session/high-load performance, public HTTP, other platforms/clients and advanced authoring are outside this stable profile. Automated approvals are explicit test doubles, not human desktop UX certification. Full production qualification remains NOT_QUALIFIED; T31–T35/G4–G6 remain future work, not completed tasks. Daily CI runs short Windows push/PR checks. The separate release workflow runs bounded real-engine/package acceptance only for version tags or explicit dispatch. No npm version is published.
Godot runs project code with your OS permissions; headless operation is not a sandbox. Configure explicit project/evidence roots and use only trusted local projects. HTTP non-loopback binding is disabled. MIT applies to application code, not automatically to website media or copied UI sources; see third-party notices before redistributing the full site.
Use Windows, Node.js 24 and Godot 4.7.2 for the accepted profile. The server requires Node.js >=20.19.0; source development also needs the current toolchain. Clone the release tag for a reproducible starting point:
git clone --branch v0.2.8 https://github.com/EVEDensity/Wheel-Mcp.git
cd Wheel-Mcp
npm.cmd run go:globalGlobal setup also includes project configuration. It installs dependencies,
builds, detects Godot and updates supported client entries. Existing JSON entries
retain their environment, roots/scopes and client settings; changed JSON and
.env files are backed up before writing. Malformed JSON is left unchanged.
Keep backups private because they may contain credentials. The installer configures
the Wheel-Mcp checkout, not every separate game workspace.
Restart your client and call get_godot_version to verify the connection.
Before opening your own game, set explicit project/evidence roots in the server environment. Follow the first-project guide for a read-only starting configuration and troubleshooting if the client cannot connect. Download from GitHub Releases or build from source; this release was not published to npm.
- Windows shortcut: double-click install.cmd for project setup; use the global command for Codex. If PowerShell blocks npm, use
npm.cmd. - Godot not found: set
GODOT_PATH=/absolute/path/to/godotin the repository's.envand retry. Setup updates this file when Godot is detected. - Start the service only: after installation,
npm run mcpstarts the MCP service, not a game.
Use the following as an alternative to one-command setup.
Install Godot and Node.js >=20.19.0; also satisfy the installed development toolchain's requirements. On Windows:
git clone https://github.com/EVEDensity/Wheel-mcp.git
cd Wheel-mcp
npm.cmd ci
npm.cmd run buildReplace every example path with your own absolute path. Merge these entries into existing configuration rather than overwriting it.
Cursor configuration
Use your game's workspace .cursor/mcp.json:
{
"mcpServers": {
"wheel-mcp": {
"command": "node",
"args": ["D:/tools/Wheel-mcp/build/src/mcp-server-sdk.js"],
"env": { "GODOT_PATH": "D:/tools/Godot_console.exe" }
}
}
}Codex configuration
Use ~/.codex/config.toml:
[mcp_servers.wheel-mcp]
command = "node"
args = ["D:/tools/Wheel-mcp/build/src/mcp-server-sdk.js"]
[mcp_servers.wheel-mcp.env]
GODOT_PATH = "D:/tools/Godot_console.exe"Reload your client and ask it to call get_godot_version. If Node is not on the client's PATH, use its absolute executable path.
MCP launch_project and open_runtime_bridge default to headless: true: logic,
physics, input and state checks run without a game window. Open one runtime bridge,
then reuse its returned session_id as sessionId for subsequent
call_runtime_bridge requests; stop it when finished. Do not reopen the bridge for
every query. Existing editor tools connect to an authorized editor; they do not
launch another editor.
Screenshots still need a real renderer, not a dummy/headless framebuffer.
capture_runtime_screenshot and screenshot-enabled dev_loop now start off-screen
and minimize an unfocusable render window. A taskbar entry may remain; OS/driver
startup or error dialogs are not suppressed. This is not a promise that arbitrary
project scripts can never request another window or change focus during startup.
For repeated screenshots use open_runtime_bridge with headless: false, background: true and reuse its session. Request headless: false, background: false
only for an intentional visible preview. One-shot screenshots still use a separate
process; existing headless sessions cannot be converted to rendered ones in place.
Restart the MCP server after updating to load the new code/bridge. CLI/core launch
defaults are unchanged; use --headless true for CLI background launches.
Bridge 0.3.5 advertises screenshot.observation/v1: screenshots include request/readback
frame and scene identities, observed window/focus/mouse state and renderer information.
Readback waits for its own deferred forced draw; overlapping captures and scene changes
return CONFLICT. These observations do not certify OS input isolation, arbitrary game
state-to-pixel consistency or screen present. A Windows/Godot 4.7.2 capture reported
focused:true while minimized and unfocusable; the no-focus acceptance remains FAIL,
with OS foreground ownership unmeasured. See capture evidence and SDK session use.
GitHub CI is enabled for pushes and pull requests to main. Pages publishes the existing showcase. A separate tag/manual release workflow packages and publishes only after its bounded acceptance passes; none of these workflows publishes to npm.
The retained Windows workflow runs npm run check
(one build, style/lint, core MCP transport, approval/transaction safety and site
checks). Dependency auditing runs on manifest/lockfile changes, unknown diffs or
manual dispatch; obsolete runs are cancelled. In Actions, manually enable
engine to add the short headless Godot smoke. No automatic engine matrix,
release gate, full regression or soak runs; failure diagnostics expire after
seven days. CI passing is not release qualification.
Use npm run check for daily work, npm run check:full for full regression,
and npm run test:godot-ci for the small native smoke. npm test still runs all
tests. npm run release:gate -- --plan previews the bounded acceptance steps
without running them or publishing. Follow the GitHub release procedure
for version tags, artifacts and failure recovery.
Try asking your connected client:
Inspect this scene and check whether Camera2D is enabled at runtime.
Run the test scene, send input, and collect logs and a screenshot. Report failed assertions with evidence.
After applying this patch, run the same checks again and compare the results.
These are client workflow examples, not guarantees of autonomous completion. See the tool catalog for actual interfaces.
Reproduce the bundled runtime check
From the repository root, import the fixture first:
$env:GODOT_PATH = 'D:/tools/Godot_console.exe'
$repo = (Get-Location).Path
& $env:GODOT_PATH --headless --path "$repo/tests/fixtures/runtime-behavior" --editor --importThen ask the connected client to call dev_loop with the following arguments, replacing the repository prefix. This is a minimal state/physics fixture, not a polished game demo.
{
"projectPath": "D:/games/Wheel-mcp/tests/fixtures/runtime-behavior",
"bridgePath": "D:/games/Wheel-mcp/godot-plugin/runtime_bridge.gd",
"evidenceDir": "D:/games/Wheel-mcp/runs/readme-smoke",
"scenePath": "res://main.tscn",
"actions": [{ "method": "wait_physics_frames", "params": { "frames": 12 } }],
"checks": [
{
"id": "camera-enabled",
"method": "get_property",
"params": { "nodePath": "Camera2D", "property": "enabled" },
"path": "value",
"op": "equals",
"expected": true
}
],
"screenshot": true,
"maxRetries": 0,
"timeoutMs": 30000,
"responseMode": "compact"
}Expected result: PASS, zero diagnostic errors, and a 320 × 180 screenshot. The README smoke test reads these arguments directly; an engine test that is skipped is not a successful runtime validation.
- Runtime property changes do not imply a saved editor scene. Optional editor tools require a separately authorized running editor and support only their declared native types. See the editor bridge contract.
- Project-file writes normally require the client's separate form confirmation of the exact transaction.
approved: trueis not permission. Clients without form support fail closed unless a separate, exact local preauthorization policy is configured; do not disable approval checks. See the transaction contract. - Persistent sessions and one-shot runs use separate instances; do not assume they share state.
- Only run trusted projects. Project scripts execute code; this server is not an operating-system sandbox.
- Advanced 3D, animation, and shader workflows are not advertised as complete. See the roadmap before depending on them.
Editor authoring: implemented subsets and important gaps
Declared scene operations cover node creation, deletion, rename, reparenting, controlled instantiation and inheritance overrides. A batch is one native Godot Undo/Redo action; saving requires separate exact approval. Save checks reload the actual native staged bytes, and tests also close and reopen the editor. The product does not automatically reload the live document.
- Scenes and resources: at most 32 operations per batch, 100 nodes per scene and 14 declared resource types in public v0.2.8; main adds bounded GradientTexture2D and ImageTexture (16 total). Documents containing scripts, undeclared node classes or unique-name nodes are not supported by native batches. Inherited scenes require explicit bounded overrides. Approved
.tscnfile writes are not native editing or native undo. - UI: basic controls, containers, Theme/StyleBoxFlat and limited
pressed → hide/showconnections. Main development adds bounded LineEdit, ScrollContainer, plain-text RichTextLabel and TextureRect authoring with native undo/save-reopen checks. TextureRect supports stable expand modes, stretch/flips, inline two-stop native gradients and PNG snapshots up to 32×32. PNG sources require SHA-256, at most 16 KiB and non-interlaced 8-bit RGB/RGBA with no metadata/profile chunks; approval binds their bytes before embedding independent native pixels. This is not a live imported-texture dependency or importer-cache loading. External exported textures require an explicit unique copy. Upgrade host/plugin together (bridge 0.3.7); these changes are not in the public v0.2.8 package. Larger/arbitrary images, SVG, CompressedTexture2D, RichTextLabel BBCode/images/links/effects/manual format stacks, script callbacks, IME and font graphs remain outside scope. - 3D and physics: basic transforms, meshes, static collisions, Area3D, RayCast3D and bounded shape queries. Not complete character/rigid-body authoring, skeletal workflows, navigation baking or contact-event history.
- 2D sprites (main): single-frame Sprite2D, centered/offset/flips and existing scoped inline PNG/gradient textures, with native undo and actual save/reopen checks. No arbitrary file loads, frame sheets, regions, materials or character scripts. See the sprite contract.
- 2D character workflow (main): native CharacterBody2D creation and six bounded configuration fields, shape/visual composition, exact approval, undo and saved reopen. Runtime bridge 0.3.3 extends explicit short physics-frame
step_character_2dmovement with bounded world-Y gravity, fresh flat-floor jumps, native wall/floor/ceiling readback and operation replay. No idle gravity, keyboard consumption, permanent controller or script attachment. See the character contract and gravity/jump extension. - Committed text input (main): runtime bridge 0.3.4 /
input.text_scalar/v1addsinject_inputparams{type:"text",text:"中"}for one Unicode scalar through native GUI input. It follows existing game focus, preserves operation replay and requires actual control readback; not IME, paste, OS keyboard automation or automatic node targeting. See the text input contract. - Animation: local 2D/3D position keys, bounded state machines and two-source Blend2. Main development adds local Node2D rotation (radians, −32…32) and positive scale (each axis 1/16…16) value tracks, plus native Node3D
rotation_3dunit-quaternion andscale_3dpositive Vector3 tracks. Native undo and safe save/reopen checks remain mandatory. Upgrade host/editor plugin together (bridge 0.3.10, independentscene.animation_transform2d/v1,scene.animation_transform3d/v1andscene.animation_copy/v1capabilities); these changes are not in the public v0.2.8 package. The newanimation_copyoperation reads a project-local, standalone native Animation.tres(16 KiB maximum), verifies its SHA-256, maps source nodes explicitly, and creates an independent local library without rewriting its source. Only bounded position / 2D rotation / positive 2D scale value tracks are accepted for copying, not arbitrary FBX/GLB or dedicated 3D transform source tracks. 3D authoring uses native quaternion interpolation, not Euler/degree conversion or multi-turn spin authoring. Skeletal/audio/method tracks and in-place imported-animation editing remain unsupported. - Materials and shaders: basic material fields, fixed shader text templates and bounded Color/Mix graphs. Not arbitrary shader source or complete PBR/VisualShader editing.
Advanced authoring remains experimental under the local release profile. Completed T12–T21 records describe historical acceptance of their declared subsets, not completion of both roadmap directions below. See the UI, physics, animation and shader contracts.
Personal-maintainer delivery uses a bounded Windows/local scope, ordinary hosted CI and the automatic GitHub token, without organization-only permissions. See the completion and maintenance checklist. The extensions below are future work, not mandatory blockers for every release.
Main also adds bounded native wheel input (input.mouse_wheel/v1) for viewport
coordinates, four directions and factor >0..8. It checks real ScrollContainer
behavior, not OS mouse control; injection acceptance alone is not consumption.
The limited local release is available. The following work extends its scope; existing bounded editor/semantic implementations are not promises of complete authoring support. See the implementation plan and task state for individual acceptance records.
- Reliability beyond the local profile: long-session/high-load and independent-machine installation checks.
- Broader editor-native editing: expand bounded scene/resource operations while retaining native undo and safe save/reopen verification.
- Broader Godot workflows: bounded, tested support for UI, 3D, animation, materials, shaders, and physics.
- Project intelligence and context: semantic resource indexing, structured Resources/Prompts, and predictable context budgets.
- Client compatibility and verification: Codex/Cursor integration tests, reproducible operation sequences, external patch validation, and regression evidence.
- Production reliability and safety: cross-platform validation, installation/upgrades, long-running stability, permission boundaries, and failure recovery.
Help with reproducible bugs, real-engine/client testing, documentation, translations, or authorized demos. For a larger change, open an Issue to agree on scope before implementation. Keep PRs focused and include a minimal fixture when possible.
npm.cmd run checkEngine-related changes also need real Godot tests with GODOT_PATH configured. Include versions and sanitized logs in reports. Never commit secrets, private project content, or assets without permission. Read CONTRIBUTING.md before starting.
- Documentation index and first-project setup
- Troubleshooting and support
- Tool catalog
- Feature status, limitations and proposed priorities (Chinese)
- Development loop
- Client repair protocol
- Deployment and security boundaries
- Implementation roadmap (Chinese)
MIT. Independent community project; not an official Godot, OpenAI, or Cursor product.
Star to follow progress. Fork and open a PR to help build it.
Open the existing project showcase.
It introduces the product; browser demos do not connect to your local MCP server.
The static website and browser playground live in docs/. Run
npm run site:serve and open http://127.0.0.1:4173/Wheel-mcp/.
Run npm run site:test for static-link and game-logic checks.
See website setup and game integration.
By EVEDensity.
