Godot MCP

Generate a natural language description of the current 3D scene.

Design a game from a natural-language concept using AI.

Export the Godot project and optionally ship to itch.io.

List fleet exchange depot assets and pipeline readiness.

Import a mesh from the fleet exchange into Godot (requires godot-bridge).

Fleet exchange pipeline - consolidated portmanteau. ## Return Format {"success": bool, ...} ## Examples await fleet_ops(operation="exchange_status") await fleet_ops(operation="import", path="models/scene.glb", name="Imported") await fleet_ops(operation="worldlabs_get", world_id="abc123")

Fetch World Labs asset URLs (mesh, splats, panorama) via worldlabs bridge API.

Download World Labs collider GLB and import into Godot via godot_import_glb bridge.

Download Chisel collision GLB to _exchange/models/worldlabs/ (no Godot import).

Download SPZ splat to exchange for Spark/Unity - not imported to Godot yet.

Generate dialogue scripts and optional Dialogic timelines from GamePlan narrative. Creates a self-contained DialogueManager.gd from NPC dialogues. If Dialogic plugin is installed (addons/dialogic/), also generates .dtl timeline files for each NPC. ## Return Format {"success": bool, "files": [str], "count": int} ## Examples await generate_dialogue(game_plan_json='...', game_project_path='C:/MyGame')

Generate GDScript files; optionally persist to a Godot project.

Generate GUT test scripts for generated game logic and optionally run them. Installs GUT plugin if not present, generates test scripts from the game plan's script specs, writes them to ``res://test/unit/``, and runs them via Godot headless CLI. ## Return Format {"success": bool, "tests": {str: {"passed": bool, "assertions": int, ...}}, "summary": str} ## Examples await generate_game_tests(game_plan_json='...', game_project_path='C:/MyGame')

Generate Marble worlds and stage collider GLBs to fleet exchange.

Add a dynamic light source to the Godot scene. Supports directional (sun-like parallel rays), ambient (environment fill), and omni (point) light types. ## Return Format {"success": bool, "data": {"created": bool, "name": str, "type": str, "intensity": float}} ## Examples await godot_add_light(light_type="directional", intensity=2.0) await godot_add_light(light_type="omni", name="KeyLight", position_x=0, position_y=3, position_z=5) await godot_add_light(light_type="ambient", intensity=0.3)

Animate GPU particles along a previously loaded velocity field. Adjusts particle emission box to match velocity field bounding box, sets initial velocity range from field vectors, and enables particle emission. ## Return Format {"success": bool, "data": {"animated": bool, "particle_system": str, "velocity_field": str, "speed_multiplier": float, "point_count": int}} ## Examples await godot_animate_streamlines(velocity_field="FlowData", particle_system="CFD_Flow", speed=2.0)

Read and edit animation keyframes and tracks on an AnimationPlayer. Query existing animations, inspect their tracks down to individual keyframes, insert or remove keyframes, and change track interpolation modes. ## Return Format {"success": bool, "data": {"node": str, "animation": str, ...}} ## Examples await godot_animation(operation="list_animations", node="AnimationPlayer") await godot_animation(operation="list_tracks", node="AnimationPlayer", animation="walk") await godot_animation(operation="list_keyframes", node="AnimationPlayer", animation="walk", track=0) await godot_animation(opera…

Capture the current Godot viewport as a PNG image. Saves a screenshot of the active viewport to disk and returns the path and dimensions. The Godot bridge must be connected. ## Return Format {"success": bool, "data": {"path": str, "width": int, "height": int, "format": "png"}} ## Examples await godot_capture_viewport() await godot_capture_viewport(output_path="C:/captures/scene.png")

Create a Camera3D with orbit controls in the Godot scene. Sets the camera as active (current=true), attaches a GDScript-based orbit controller with mouse drag and scroll-zoom support. ## Return Format {"success": bool, "data": {"created": bool, "name": str, "fov": float, "position": {"x": float, "y": float, "z": float}}} ## Examples await godot_create_camera(name="RenderCam", position_y=10, position_z=15, fov=60)

Fetch Godot engine documentation as clean markdown. Retrieves class reference pages from docs.godotengine.org, version-matched to the running Godot engine. The documentation is returned as rendered markdown with working anchor links. ## Return Format {"success": bool, "class": str, "version": str, "content": str, "sections": list} ## Examples await godot_docs(query="Node3D") await godot_docs(query="AnimationPlayer", section="methods") await godot_docs(query="TileMapLayer")

Export a Godot sample or custom project for itch.io (Web or Windows). ## Examples await godot_export_release(target="web", game="dodge")

Export the current Godot scene to HTML5/WebAssembly. Attempts in-editor export via the GDScript bridge first. Falls back to godot --headless --export-release if the bridge reports templates unavailable. ## Return Format {"success": bool, "data": {"exported": bool, "message": str, "output_path": str}} ## Examples await godot_export_web(output_path="C:/builds/godot-web/index.html")

Control the game clock for deterministic playtesting. **freeze** - pauses the game loop (``Engine.time_scale = 0``). The bridge keeps running so you can send input, read state, or set up scenarios. **unfreeze** - resumes normal game speed. **step** - advances the game by *frames* frames with real time-scale, then automatically re-freezes. Use after a freeze to tick the game forward deterministically. ## Return Format {"success": bool, "data": {"state": str, "time_scale": float}} ## Examples await godot_game_time(action="freeze") await godot_game_time(action="step", frames=60) await godot_…

Generate a procedural texture (gradient, noise, checker, solid) in Godot. Creates a runtime texture using Godot's Image API, saves it as PNG, and returns the path. The texture can be used with godot_set_material or as a sprite texture. ## Return Format {"success": bool, "data": {"path": str, "width": int, "height": int, "texture_type": str}} ## Examples await godot_generate_procedural_texture(texture_type="gradient", width=512, height=128, colors=["#ff0000", "#0000ff"]) await godot_generate_procedural_texture(texture_type="noise", width=256, height=256, colors=["#1a1a2e", "#e94560"], freque…

Check whether the Godot engine is running in headless mode. Returns the headless status and a suggested CLI command for headless script execution with godot --headless --script. ## Return Format {"success": bool, "data": {"headless": bool, "script_path": str, "message": str}} ## Examples await godot_headless_verify(script="res://tests/mcp_headless_test.gd")

Get context-aware help for godot-mcp tools and workflows. Returns markdown with tool categories, example commands, and usage tips. Use ``topic`` to drill into a specific area. ## Return Format {"success": bool, "help": str, "topic": str} ## Examples await godot_help() await godot_help(topic="playtesting") await godot_help(topic="scene")

Import a GLB/GLTF 3D model into the current Godot scene. Uses Godot 4.0's native GLTFDocument importer to load meshes, materials, and node hierarchy from glTF 2.0 binary (.glb) or text (.gltf) files. This unlocks the blender-mcp → godot-mcp pipeline. ## Return Format {"success": bool, "data": {"imported": bool, "name": str, "total_nodes": int, "mesh_count": int}} ## Examples await godot_import_glb(path="C:/exchange/robot.glb", name="Robot", scale=0.01) await godot_import_glb(path="C:/exchange/scene.gltf")

Import an OBJ 3D model into the current Godot scene. Uses Godot 4.0's ResourceLoader to import Wavefront OBJ files (.obj + .mtl). Supports the freecad-mcp CFD streamline export → godot-mcp pipeline. ## Return Format {"success": bool, "data": {"imported": bool, "name": str}} ## Examples await godot_import_obj(path="C:/exchange/streamlines.obj", name="CFD_Streamlines")

Import a 3D Gaussian Splatting (.ply or .spz) file into the Godot scene. Parses the splat file (decompressing SPZ if needed), extracts per-splat positions, SH DC colors, and covariance scales, then renders via a custom ``gaussian_splat.gdshader`` on a ``MultiMeshInstance3D``. The shader applies proper billboarded Gaussian falloff with per-splat scale. Supports ``.ply`` (binary 3DGS format) and ``.spz`` (gzip-compressed). Use ``fleet_worldlabs_stage_splat`` to download World Labs splats first. ## Return Format {"success": bool, "data": {"imported": bool, "name": str, "splat_count": int, "sha…

Import an STL mesh into the current Godot scene as a MeshInstance3D. Reads binary STL vertex/normal data, creates an ArrayMesh, and returns vertex count and AABB extents. Use in cross-repo pipeline with qcad-mcp and freecad-mcp. ## Return Format {"success": bool, "data": {"imported": bool, "name": str, "vertices": int, "aabb": {"size_x": float, "size_y": float, "size_z": float}}} ## Examples await godot_import_stl(path="C:/uploads/part.stl", name="MyPart", scale=0.01)

Import a VRM avatar model into the current Godot scene. Copies the VRM file into the project, installs the V-Sekai/godot-vrm addon if missing, and loads it via Godot's ResourceLoader which triggers the VRM addon's glTF extension importer. ## Return Format {"success": bool, "data": {"imported": bool, "name": str}} ## Examples await godot_import_vrm(path="~/.avatarmcp/models/Nekomimi-chan.vrm", name="Miko")

Inspect a resource file loaded in the Godot engine. Type-aware inspection for: - **SpriteFrames**: animation names, frame counts, speed, loop - **TileSet**: source count, source IDs, tile counts - **Material** (StandardMaterial3D): albedo, roughness, metallic, emission - **ShaderMaterial**: shader path, parameter list with values - **Texture2D**: width, height, format, mipmap status - **Generic**: property list for any other resource type ## Return Format {"success": bool, "data": {"resource": {"path": str, "type": str, ...}}} ## Examples await godot_inspect_resource(path="res://characters/…

List available VRM models in the shared avatar depot. ## Return Format {"success": bool, "data": {"models": list[dict], "depot_path": str}} ## Examples await godot_list_vrm()

Load a CSV velocity field dataset into the Godot scene. Parses CFD/FluidX3D-style CSV with position and vector columns. Stores points and vectors as node metadata for downstream particle animation. ## Return Format {"success": bool, "data": {"loaded": bool, "name": str, "point_count": int, "bbox": {"min_x": float, ..., "max_z": float}}} ## Examples await godot_load_velocity_field(csv_path="C:/data/velocity_field.csv", name="FlowData")

Play or list animations on an imported GLB character via AnimationPlayer. Use after godot_import_glb with a GLB that includes baked animation tracks (typical path: blender-mcp VMD bake -> GLB export -> godot_import_glb). ## Return Format Playing: {"success": bool, "data": {"playing": true, "animation": str, "available_animations": list}} Listing: {"success": bool, "data": {"listed": true, "animations": list}} ## Examples await godot_play_animation(root_name="Dancer", animation="") await godot_play_animation(root_name="Dancer", animation="dance_01", loop=True)

Read Godot performance metrics and detect frame spikes. Snapshots read 14 metrics from Godot's ``Performance`` singleton: FPS, process time, physics time, memory (static/dynamic), object/node/orphan counts, render draw calls/primitives/video memory, physics active objects/collisions, audio latency. Enable auto-sampling to record a rolling history of 300 frames, then use ``history`` to detect anomalous spikes (>2 stddev from the window mean). ## Return Format {"success": bool, "data": {"snapshot": dict, "enabled": bool, "spikes": list}} ## Examples await godot_profile(operation="snapshot") …

Read properties of a single node by path or name. Returns effective properties (position, rotation, scale, velocity, visible, current_animation) and child list. Lightweight alternative to read_scene_tree when you only need one node. If the node defines ``_mcp_state()``, that takes priority over auto-collected properties. ## Return Format {"success": bool, "data": {"node": {"name": str, "type": str, "path": str, ...}}} ## Examples await godot_read_node(node="Player") await godot_read_node(node="World/Camera3D")

Read the full Godot scene tree as a nested JSON structure. Returns the root node with all children recursively, showing name, type, and path for each node in the tree. ## Return Format {"success": bool, "data": {"scene_tree": {"name": str, "type": str, "path": str, "children": [...]}, "node_count": int}} ## Examples await godot_read_scene_tree()

Manage the Godot scene tree: add, remove, modify, animate nodes, spawn a test fixture, or save the scene. Portmanteau for 7 bridge actions: add_node, remove_node, modify_node, save_scene, animate_node, stop_animation, fixture_spawn (the last three backported 2026-09-03 from overte-mcp/resonite-mcp/unity3d-mcp's identical features). ## Return Format {"success": bool, "data": {...}} ## Examples await godot_scene(operation="add_node", parent=".", node_type="Camera3D", name="GameCam") await godot_scene(operation="remove_node", name="OldNode") await godot_scene(operation="modify_node", node_path…

Write a setting to the project.godot configuration file. Modifies the res://project.godot INI-style file via ConfigFile API. ## Return Format {"success": bool, "data": {"updated": bool, "section": str, "key": str, "value": str}} ## Examples await godot_set_config(section="application", key="config/name", value="My CFD Project") await godot_set_config(section="rendering", key="quality/driver/driver_name", value="GLES3")

Assign a StandardMaterial3D (PBR) to a mesh node in the Godot scene. Sets albedo color and roughness. The node must already exist in the scene tree. ## Return Format {"success": bool, "data": {"set": bool, "node": str, "color": str, "roughness": float}} ## Examples await godot_set_material(node="STL_Mesh", color="#4488ff", roughness=0.3)

Shut down the godot-mcp server process. ## Return Format {"success": bool, "message": str} ## Examples await godot_shutdown(confirmed=True)

Simulate input in the Godot engine - keyboard, action, joypad, mouse, and text. Dispatches each action dict by its key signature. Legacy ``{"key": ...}`` entries use ``InputEventKey`` with optional hold-timed release. New formats use ``Input.action_press`` (analog actions), ``InputEventJoypadMotion`` / ``InputEventJoypadButton``, ``InputEventMouseMotion``, ``InputEventMouseButton``, and per-character ``InputEventKey`` (text). ## Return Format {"success": bool, "data": {"actions_processed": int, "results": [...]}} ## Examples # Legacy key press with hold await godot_simulate_input(actions=[{…

Create a GPUParticles3D system in the Godot scene. Sets up a particle system with configurable emission box, count, and draw pass sphere mesh. Use after godot_load_velocity_field for CFD visualisation. ## Return Format {"success": bool, "data": {"spawned": bool, "name": str, "count": int, "particle_system": str}} ## Examples await godot_spawn_particles(count=5000, name="CFD_Flow", spread_x=10, spread_y=10, spread_z=10)

Read structured runtime state from the game scene. Two modes: - **Watch group** (omit ``node_names``): returns state for every node in the ``mcp_watch`` group. Nodes in this group can define a ``_mcp_state()`` method for custom state, or fall back to automatic property collection (position, rotation, scale, velocity, visible, current_animation). - **Named lookup** (provide ``node_names``): finds each node by name anywhere in the tree and returns its state, regardless of watch group membership. Cheaper than ``read_scene_tree`` - returns structured JSON without full hierarchy. ## Retu…

Query the Godot engine for version, scene root node count, and current FPS. Calls the GDScript bridge over TCP to read live engine state. ## Return Format {"success": bool, "data": {"godot_version": str, "node_count": int, "fps": float, "bridge_connected": bool}} ## Examples await godot_status()

Step the game frame-by-frame until a GDScript expression becomes true. Freeze the clock first with ``godot_game_time(action="freeze")``, then call this to advance one frame at a time until the condition is met. The clock re-freezes automatically when the condition triggers (or on timeout). The ``timeout_frames`` param prevents runaway conditions. The condition expression runs in the context of the scene root, so ``get_node("Player")`` resolves relative to the root of the active scene. ## Return Format {"success": bool, "data": {"condition_met": bool, "frames_elapsed": int, "timed_out": bool…

Read or edit TileMapLayer and GridMap cells. For TileMapLayer: reads cell source IDs, atlas coordinates, and alternative tiles. For GridMap: reads cell item IDs and orientations. The ``set_cell`` operation writes cells that would otherwise be base64-encoded in the ``.tscn`` file - this is the only practical way for agents to edit tilemap data. ## Return Format {"success": bool, "data": {"node": str, "type": str, "cells": [...], "cell_count": int}} ## Examples await godot_tilemap(operation="read", node="GroundLayer") await godot_tilemap(operation="set_cell", node="GroundLayer", cells=[{"x": …

Validate all MeshInstance3D meshes in the scene for geometric corruption. Checks each mesh surface for: - **NaN/inf values** in vertex positions (segfault risk at render time) - **Zero-length normals** (causes flat shading on affected faces) - **Degenerate triangles** (zero-area faces from collapsed geometry) - **Empty surface arrays** (missing vertex data) Catches silently corrupt procedural mesh data that masquerades as lighting bugs or invisible geometry - the kind of issue that wastes hours of debugging because there's no visible error. ## Return Format {"success": bool, "data": {"total…

Download and install a community Godot plugin from GitHub into the project. Delegates to the module-level install_community_plugin(). See docs/godot-ecosystem.md for the full plugin catalog. ## Return Format {"success": bool, "plugin": str, "addon_path": str, "message": str} ## Examples install_community_plugin(plugin_name="dialogic", project_path="C:/MyGame") install_community_plugin(plugin_name="gut", project_path="C:/MyGame")

Install the Godot MCP bridge addon into a Godot project. Copies mcp_bridge.gd and creates plugin.cfg in the project's addons/mcp_bridge/ directory. The addon must be registered as an Autoload in Godot (Project > Project Settings > Autoload). ## Return Format {"success": bool, "message": str, "addon_path": str} ## Examples install_godot_addon(project_path="C:/MyGodotProject")

Query api.itch.io/wharf/latest for the newest build version on a channel.

itch.io publishing - consolidated portmanteau for Butler operations. ## Return Format {"success": bool, ...} ## Examples await itch_ops(operation="status") await itch_ops(operation="export", target="web", game="dodge") await itch_ops(operation="push", upload_dir="build/dodge/web", itch_target="user/game") await itch_ops(operation="ship", target="web", game="dodge", itch_target="user/game")

Upload a build directory to itch.io via Butler push. ## Examples await itch_push(upload_dir="...", itch_target="you/my-game", channel="html")

Preview Butler push diff (NEW/MODIFIED/DELETED) before uploading. ## Examples await itch_push_preview(upload_dir="D:/Dev/repos/godot-mcp/build/little-game/dodge/web")

Check Butler install, API key env, and default itch.io slug. ## Return Format {"success": bool, "butler": {...}, "auth": {...}, "defaults": {...}} ## Examples await itch_status()

Build an MCPB bundle from a tool sequence. This creates a portable .mcpb file. ## Return Format {"success": bool, "path": str, "manifest": {...}} ## Examples await mcpb_build(name="My Scene", description="A test scene", tool_sequence=[{"tool": "godot_create_camera", "params": {}}])

Inspect the contents of an .mcpb bundle without extracting. ## Return Format {"success": bool, "manifest": {...}} ## Examples await mcpb_inspect(bundle_path="my_scene.mcpb")

Import CFD velocity data and spawn GPU particles for flow visualization.

Apply a prefab template, executing its tool sequence with given parameters. ## Return Format {"success": bool, "prefab": str, "results": [...]} ## Examples await prefab_apply(prefab_id="standard_lighting", params={"intensity": 2.0})

List available prefab templates, optionally filtered by category. ## Return Format {"success": bool, "prefabs": [...]} ## Examples await prefab_list() await prefab_list(category="lighting")

Execute a prompt template with given parameters and return the LLM response. Uses ctx.sample() for the LLM call. ## Return Format {"success": bool, "prompt": str, "response": str}

List available prompt templates. ## Return Format {"success": bool, "prompts": [...]}

Set up a complete 3D scene with lighting, camera, and environment.

Export Godot build, optionally preview and push to itch.io in one flow. ## Examples await ship_to_itch(target="web", game="dodge", itch_target="you/my-game", channel="html")

Export Windows build, stage to exchange, generate VDF, upload via steam-mcp.

Upload staged build to Steam beta branch via steam-mcp (dry_run default true).

Upload staged build to Steam default (live) branch via steam-mcp.

Export HTML5 build, preview Butler diff, push to itch.io.

Show fleet exchange depot status as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_fleet_status_card()

Show Godot engine status as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_godot_status_card()

Show itch.io/Butler publishing status as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_itch_status_card()

Show Godot performance metrics as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_profile_card()

Show a single node's properties as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_read_node_card(node="Player")

Show structured game state as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_state_digest_card() await show_state_digest_card(node_names=["Player"])

Show Steam publishing readiness as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_steam_status_card()

Show mesh validation results as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_validate_meshes_card()

Capture and show the Godot viewport as a Prefab card. Requires the Godot bridge to be connected. Falls back to a hint if the bridge is not running. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_viewport_card()

Show built-in workflows as a rich Prefab card. ## Return Format ToolResult with PrefabApp structured_content; plain text fallback. ## Examples await show_workflows_card()

Locate Godot and launch it headless with the MCP bridge addon. Finds godot.exe via GODOT_PATH, PATH, or common install dirs, then starts it with ``--headless`` and the bridge project. Call ``godot_status`` after ~5s to verify the bridge is connected. ## Return Format {"success": bool, "pid": int, "godot": str, "project": str, "log": str, "message": str} ## Examples await start_bridge() await start_bridge(project_root="C:/MyGame")

Return Steam Direct / release checklist from steam-mcp.

Pricing and revenue guidance (manual Steamworks steps).

Steam publishing via steam-mcp - consolidated portmanteau. ## Return Format {"success": bool, ...} ## Examples await steam_ops(operation="status") await steam_ops(operation="stage", game="dodge") await steam_ops(operation="prerelease", dry_run=True) await steam_ops(operation="ship", game="dodge", phase="release", dry_run=True)

Export Windows build and stage files to fleet exchange for Steam depot upload.

Check steam-mcp connectivity, Steam App/Depot IDs, and steamcmd readiness.

Get AI suggestions for improving scene lighting.

Check the V-Bot bridge connection status. ## Return Format {"success": bool, "connected": bool, "subscribed_bots": int, "last_error": str | None}

Connect to the V-Bot Mind WebSocket bridge for autonomous NPC behavior. Opens a WebSocket to vbot-mind-mcp's engine bridge (port 11080). Once connected, V-Bots can perceive the Godot scene and send actions. ## Return Format {"success": bool, "message": str, "data": {"connected": bool}} ## Examples vbot_connect() vbot_connect(url="ws://127.0.0.1:11080")

Disconnect from the V-Bot Mind bridge. ## Return Format {"success": bool, "message": str}

Send perception data from the Godot scene to a V-Bot. Feeds the V-Bot's brain with what it sees in the world. The bot will incorporate this into its next think cycle. ## Return Format {"success": bool, "message": str, "data": {"bot_id": str}}

Poll the V-Bot bridge for pending actions from bots. Call this in a loop in the Godot game loop to receive bot actions (MOVE, SPEAK, INTERACT, IDLE, FLEE) and apply them to the scene. ## Return Format {"success": bool, "actions": [{"bot_id": str, "type": str, ...}]} ## Examples vbot_poll_actions() vbot_poll_actions(timeout=0.5)

Send a V-Bot's current position and animation state from Godot to the brain. ## Return Format {"success": bool, "message": str}

Subscribe to V-Bot updates. Receives actions when bots think in the game loop. ## Return Format {"success": bool, "message": str}

List all built-in agentic workflows. ## Return Format {"success": bool, "workflows": [{"name": str, "description": str, "steps": int}]} ## Examples await workflow_list()

Run a built-in agentic workflow. Executes a predefined multi-step workflow, injecting context variables. ## Return Format {"success": bool, "workflow": str, "steps_completed": int, "results": [...]} ## Examples await workflow_run(workflow_name="scene_setup") await workflow_run(workflow_name="particle_cfd", csv_path="C:/data/flow.csv")