# @shin2344234/godot-mcp [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/shin2344234/godot-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 1965  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shin2344234-godot-mcp

## Description
MCP server for the Godot 4 engine: edit scenes, nodes and scripts, run the game and read errors, through a live editor bridge or headless Godot.

## Tools
Capabilities this server exposes over MCP:

- **godot_status** — Godot status: call this first. Shows the project, whether the live editor is connected (open scenes, unsaved changes, playing state), the Godot executable found, and running games.
- **godot_addon_install** — Godot addon: install or update addons/godot_mcp (the editor bridge and game runtime this server needs) from the copy bundled with the server, and enable it in project.godot.
- **godot_project_info** — Godot project facts from project.godot: name, Godot version, main scene, autoloads, input action names, renderer, enabled plugins, C# and test framework detection.
- **godot_project_settings** — Godot project settings: read raw values from project.godot, filtered by key prefix (e.g. "display/window", "input/jump"). Only non-default values are stored in the file.
- **godot_files_list** — Godot files: list a project folder (res://...). Skips .godot/ and .git/; hides .uid/.import sidecars and, when recursive, addons/ contents unless all. Use recursive with a glob-like "pattern" (e.g. "*.tscn") to find files by type.
- **godot_files_read** — Godot files: read a text file (script, scene .tscn, resource .tres, shader, config) with line numbers. Use offset/limit for long files.
- **godot_files_search** — Godot files: search text across project files (scripts, scenes, resources, shaders). Literal by default; set regex for a regular expression.
- **godot_files_write** — Godot files: create or overwrite a text file (e.g. a .gd script or .gdshader). GDScript files are then checked for parse and type errors (as godot_script_validate). Prefer godot_files_edit for small changes to existing files.
- **godot_files_edit** — Godot files: replace an exact snippet in a text file (old_text -> new_text). old_text must match exactly once unless replace_all. GDScript files are then checked for parse and type errors (as godot_script_validate).
- **godot_files_move** — Godot files: move or rename a file or folder, carrying its .uid/.import sidecar files. References by uid:// keep working; plain res:// references in other files are NOT updated.
- **godot_files_delete** — Godot files: delete a file (and its .uid/.import sidecars). Deleting a folder requires recursive: true. This cannot be undone.
- **godot_scene_tree** — Godot scene: show the node tree (names, types, scripts, instanced sub-scenes) of a scene. Use depth/max_nodes to keep large scenes small; start from a subtree with root.
- **godot_scene_create** — Godot scene: create a new .tscn file with a root node of the given type (e.g. Node2D, Node3D, Control, CharacterBody2D).
- **godot_scene_open** — Godot scene: open a scene in the editor so later node operations target it.
- **godot_scene_save** — Godot scene: save the edited scene in the editor (headless edits are saved automatically).
- **godot_scene_save_as** — Godot scene: save the edited scene under a new path (editor only).
- **godot_node_get** — Godot node: read a node's type, script, non-default property values and connected signals. Pass properties to read only some.
- **godot_node_add** — Godot node: add a node of a built-in type (e.g. Sprite2D, CollisionShape2D, Label) or an instance of a .tscn scene, with optional initial properties. Undoable in the editor.
- **godot_node_set** — Godot node: set one or more properties on a node (position, texture, shape, modulate, ...). Returns the values read back. Undoable in the editor.
- **godot_node_remove** — Godot node: delete a node and its children from the scene. Undoable in the editor; permanent when headless.
- **godot_node_rename** — Godot node: rename a node. Note: scripts or NodePaths that refer to the old name are not updated.
- **godot_node_reparent** — Godot node: move a node under a different parent (and/or to a child index), keeping its global transform by default.
- **godot_node_duplicate** — Godot node: duplicate a node (with children, script and properties) next to the original.
- **godot_script_attach** — Godot script: attach a .gd (or .cs) script to a node, or detach with script: null. Create the file first with godot_files_write.
- **godot_script_validate** — Godot script: check GDScript for parse/type errors without running the game. Pass a file path, or source text to check before writing.
- **godot_run_start** — Godot run: start the game (main scene, the current scene, or a given scene). Returns a run_id; read errors and prints with godot_run_output, stop with godot_run_stop.
- **godot_run_stop** — Godot run: stop a running game (the given run_id, the latest process run, or the game playing in the editor).
- **godot_run_output** — Godot run: read output and errors of a game started with godot_run_start (process or editor mode). Use level "error" to see only errors, and "since" (the "next" value from the last call) to page.
- **godot_editor_logs** — Godot editor: read messages, warnings and errors printed by the editor process (plugin and tool scripts, import errors; not a running game's prints). Repeats are merged with a count. Page with "since".
- **godot_editor_launch** — Godot editor: open this project in the Godot editor and wait until the MCP plugin connects (the plugin must be enabled in the project).
- **godot_node_instance** — Godot node: instance a .tscn as a linked sub-scene under a parent, optionally with Editable Children. Undoable in the editor.
- **godot_node_find** — Godot node: find nodes in a scene by name (glob/substring), type (incl. subclasses), group, script or property value.
- **godot_node_move** — Godot node: move a node to another position among its siblings (draw/process order). Undoable in the editor.
- **godot_node_groups** — Godot node: add or remove a node's groups (saved in the scene). Undoable in the editor.
- **godot_scene_inherit** — Godot scene: create a new scene file that inherits a base scene (like "New Inherited Scene"); opens it in the editor.
- **godot_scene_close** — Godot scene: close a scene tab in the editor. Refuses unsaved changes unless save or discard is true.
- **godot_batch_apply** — Godot scene: apply up to 100 scene edits (node.add, node.set, signal.connect, ...) to one scene in order, all-or-nothing; one undo step in the editor.
- **godot_signal_list** — Godot signal: list saved signal connections of a node or scene and flag problems (missing/mismatched handlers, unconnected _on_* methods).
- **godot_signal_connect** — Godot signal: connect a node's signal to a method (saved in the scene), optionally creating the handler stub in the target's script.
- **godot_signal_disconnect** — Godot signal: remove a saved signal connection from a scene. Undoable in the editor.
- **godot_resource_read** — Godot resource: read a .tres/.res/.gdshader (or uid://): class, uid, non-default properties, shader uniforms, theme items.
- **godot_resource_create** — Godot resource: create a resource file of any Resource class (materials, Theme, Gradient, shapes...) or a .gdshader with code.
- **godot_resource_set** — Godot resource: set properties of an existing resource file and save it (undoable in the editor; open scenes update).
- **godot_resource_deps** — Godot resource: list a file's dependencies (missing ones flagged), optionally the files that use it; resolves uid:// paths.
- **godot_visual_shader_graph** — Godot visual: edit or create a VisualShader .tres with ordered node ops (add, connect, set...).
- **godot_visual_shader_graph_read** — Godot visual: list a VisualShader's nodes (id, class, properties) and connections per shader type.
- **godot_visual_layout** — Godot visual: apply a Control layout preset, anchors/offsets, size flags or minimum size. Undoable.
- **godot_visual_shader_check** — Godot visual: compile shader code or a .gdshader/VisualShader file and report errors with line numbers.
- **godot_anim_read** — Godot animation: list an AnimationPlayer's libraries and animations, or with animation the tracks and keys of one. Pass library (a .tres) instead of a scene player to read an AnimationLibrary file.
- **godot_anim_edit** — Godot animation: create/remove/rename animations and add tracks and keys on an AnimationPlayer. ops run in order as one undo step; track paths are "Node:property" relative to the player's root_node.
- **godot_anim_tree_read** — Godot animation: show an AnimationTree's graph (states, transitions, blend points, blend tree nodes) and its parameters.
- **godot_anim_tree** — Godot animation: build an AnimationTree state machine, blend space or blend tree (states, transitions, start/end, blend points). ops run in order as one undo step.
- **godot_anim_frames** — Godot animation: read or edit the SpriteFrames of an AnimatedSprite2D/3D (or a .tres): add/rename/remove animations, speed/loop, frames cut from a sprite sheet. No ops = summary.
- **godot_grid_read** — Godot world: read a TileMapLayer/GridMap: cells, bounds and the TileSet tiles/terrains or MeshLibrary items to paint with.
- **godot_grid_edit** — Godot world: paint a TileMapLayer/GridMap with ordered ops (set, erase, fill_rect, terrain; clear wipes all cells). One undo step.
- **godot_tileset_edit** — Godot world: create/edit a TileSet .tres: atlas sources, collision (one-way), navigation, occlusion, terrains, custom data, per-tile values, alternative tiles, animation. Saved at once.
- **godot_navigation_bake** — Godot world: bake a NavigationRegion2D/3D from its child colliders, meshes, GridMaps and TileMapLayers.
- **godot_navigation_path** — Godot world: shortest path between two points over the scene's baked navigation regions.
- **godot_audio_buses** — Godot audio: list the audio buses (volume, mute, solo, send) and their effects from the project's bus layout.
- **godot_audio_edit** — Godot audio: add, remove, rename, move and set buses (volume, mute, solo, send) and their effects; saves the bus layout.
- **godot_project_set** — Godot project: change project settings (project.godot); null resets one to its default. Values are converted to each setting's type.
- **godot_input_edit** — Godot project: edit the input map (actions and their key/mouse/gamepad bindings), applied in order and saved to project.godot.
- **godot_autoload_edit** — Godot project: add, remove or reorder autoloads (global singletons loaded at startup).
- **godot_project_plugins** — Godot project: enable or disable editor plugins (addons) and list the available ones.
- **godot_project_validate** — Godot project: health check for missing dependencies, stale or duplicate UIDs, script compile errors, broken autoloads, main scene and plugins.
- **godot_import_get** — Godot import: show an asset's importer, non-default options (full: all), uid and whether its imported files exist (imports new assets first).
- **godot_import_set** — Godot import: change an asset's import options (or importer) and reimport it.
- **godot_export_presets** — Godot export: list export presets (platform, path, filters, options; secrets redacted) and whether export templates are installed.
- **godot_export_preset_set** — Godot export: change an export preset's fields/options, or create a preset, in export_presets.cfg.
- **godot_export_run** — Godot export: build the game with an export preset (release, debug, pack-only .pck/.zip, or patch); long-running.
- **godot_code_diagnostics** — Godot code: GDScript errors and warnings for .gd files or a folder, from the language server.
- **godot_code_symbols** — Godot code: outline of a .gd file (funcs, signals, vars, consts, classes with lines), or find symbols by name with query.
- **godot_code_lookup** — Godot code: hover docs, definition, references, signature, completion or highlights at a position in a .gd file.
- **godot_code_rename** — Godot code: rename a GDScript symbol across the project via the language server (skips comments/strings). dry_run previews.
- **godot_docs_search** — Godot docs: search the offline class reference (engine + project classes) by class/member name or words.
- **godot_docs_class** — Godot docs: class reference for an engine or project class, or one member ("Class.member"), as markdown.
- **godot_game_tree** — Godot game: the running game's live nodes as a flat list (path, class, script, rect/pos, visible text). Filters list matches only; text "Start" finds the button to click.
- **godot_game_get** — Godot game: current values of a live node: script variables and non-default properties (or listed ones, "prop:sub" ok), groups; optionally signal connections and script methods.
- **godot_game_edit** — Godot game: change the running game with ops in order: set properties, call a method (returns its value, awaits coroutines), spawn, remove, change/reload scene. Stops at the first failing op; earlier ops stay (no undo, nothing saved).
- **godot_game_eval** — Godot game: evaluate code in the running game: an Expression with self = node (default; autoloads and singletons by name), or a GDScript body of func run(node, tree, inputs) (use return). Off unless the server runs with --allow-eval.
- **godot_game_input** — Godot game: send input steps in order (keys, actions, clicks on positions or nodes, drags, scroll, typing, joypad, touch, waits). Reports the Control and physics object under each click.
- **godot_game_time** — Godot game: pause/resume the whole game (Godot's suspend: no node processes; SceneTree.paused untouched), step frames or physics ticks, set speed, or wait for a node, signal, condition, frames or seconds.
- **godot_game_record** — Godot game: record the game's input events (real and injected) with timestamps, stop to get them as compact JSON (or save to a file), and replay them with the original timing.
- **godot_game_screenshot** — Godot game: screenshot the running game (window, a node's viewport, or a region) or the editor's 2D/3D view, scaled down. Can save it and diff against a saved image.
- **godot_game_perf** — Godot game: performance monitors of the running game (fps, frame times, memory, objects, draw calls...); optionally sample frames (stats, spikes) and profile script functions.
- **godot_debug_state** — Godot debug: is the game stopped (breakpoint, error, pause)? Call stack and variables (locals, members, globals) of a frame.
- **godot_debug_control** — Godot debug: continue, pause, step_into/over/out (returns the new location and locals), or evaluate an expression in a stopped game (process runs).
- **godot_debug_breakpoints** — Godot debug: list, add, remove or clear breakpoints of a game started with godot_run_start (process mode), running or stopped.
- **godot_test_run** — Godot test: run GUT or GdUnit4 tests headlessly (all, a folder, a file or one test name); returns totals and failures with file:line.
- **godot_editor_ui** — Godot editor: get/set the selected nodes, open a script at a line, save all scenes and scripts, or show a toast.
- **godot_tools** — Godot tool catalog: search all available Godot operations by keyword ("search"), or get full parameter schemas for some ("describe").

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "godot-mcp": {
    "command": "npx",
    "args": ["-y","@shin2344234/godot-mcp"]
  }
}
```

## Documentation

## What @shin2344234/godot-mcp does

@shin2344234/godot-mcp gives MCP-compatible AI agents access to Godot 4 project workflows. It covers scene, node, signal, and resource inspection and editing, as well as animations, AnimationTrees, SpriteFrames, tile maps, navigation, audio buses, and visual shaders.

Project-level operations include changing settings, input actions, autoloads, import options, and export presets, including running exports. Script work includes GDScript language-server diagnostics, symbol lookup, and renaming. The server can also query the offline Godot class reference for the installed engine version.

For a running game, agents can inspect and modify nodes, send input, pause and step frames, capture screenshots, profile execution, and record or replay input. Debugging features include breakpoints, stepping, stack inspection, and variable inspection. GUT and GdUnit4 tests can be run through the server.

## How it works

The primary connection uses a live editor bridge inside the Godot project. Scene changes made through that bridge can be undone with Godot's normal Ctrl+Z action. When the editor is closed, the server can use headless Godot instead.

The package also supports work inside the running game through its in-game runtime capabilities. To verify the connection after setup, an agent can call `godot_status`. The server communicates with MCP clients, while the Godot project supplies the editor, headless, and runtime sides of the connection.

## Setup and configuration

The project must use Godot 4.7 or newer. Node.js 22 or newer is required for the regular installation; the Claude Desktop bundle includes its own Node.js runtime.

From the directory containing `project.godot`, run:

```bash
npx -y @shin2344234/godot-mcp init
```

The initializer displays its planned changes and requests confirmation. `--dry-run` previews the changes, while `--remove` reverses them. Initialization copies the editor addon into `addons/godot_mcp`, enables it, registers the server with detected agents or with clients selected through `--agents`, and adds a short entry to `AGENTS.md`.

Other installation paths include the Claude Code plugin, the `.mcpb` package for Claude Desktop, manual client configuration, and building from source. If the server was installed without `init`, run `godot_addon_install` once for each project to add the editor addon.

## Tools and capabilities

Capabilities are organized around several Godot workflows:

- Inspect and edit scenes, nodes, signals, and resources.
- Create or modify animations, AnimationTrees, SpriteFrames, tile maps, navigation, audio buses, and visual shaders.
- Change project settings, input actions, autoloads, import options, and export presets.
- Use GDScript diagnostics, symbols, renames, and offline class-reference lookup.
- Control and observe a running game, including input, pausing, frame stepping, screenshots, profiling, and input recording or replay.
- Debug with breakpoints, stepping, stacks, and variables, then run GUT or GdUnit4 tests.

_Full upstream README: https://allmcps.com/mcp/shin2344234-godot-mcp/readme_