godot-mcp: a 157-tool MCP server for driving the Godot 4.x editor and runtime

The gap this fills: Godot has no scripting hook for an assistant

Godot stores almost everything a project is in plain text. Scenes are .tscn files, resources are .tres files, settings live in project.godot, and export configuration sits in export presets. That means an assistant does not strictly need a plugin to edit a Godot project; it needs a way to parse and rewrite those files without corrupting them, plus a way to reach into a game while it is running. Those are two different problems, and godot-mcp addresses them with two different mechanisms in one server. The README frames the scope as full control over the engine, listing 157 tools across networking, 3D and 2D rendering, UI, audio effects, animation trees, file I/O, runtime code execution, property inspection, scene manipulation, signal management, physics and project creation. The audience is a developer who already works from a terminal and wants an assistant to do the mechanical parts of scene assembly and runtime poking, not someone looking for an in-editor assistant panel.

Two execution paths: headless GDScript operations and a TCP runtime bridge

The architecture the README describes comes from the upstream project it credits, Coding-Solo's godot-mcp: a TypeScript MCP server, a headless GDScript operations system, and a TCP-based runtime interaction server. The fork keeps that foundation and widens it. The headless path handles anything that can be done on files without a running game. read_scene parses a .tscn file and returns the node tree with properties as JSON; modify_scene_node and remove_scene_node change that tree; attach_script binds a GDScript file to a node; create_resource writes .tres files such as materials and themes. read_project_settings and modify_project_settings do the same for project.godot, and list_project_files filters by extension. The runtime path is the other half. game_eval executes arbitrary GDScript inside the running game and returns values, with await supported for async code, and the README notes it works while the game is paused because it uses PROCESS_MODE_ALWAYS. Around that sit game_get_property and game_set_property for any node path, game_call_method, game_get_node_info for full introspection of properties, signals, methods and children, and scene-level operations like game_instantiate_scene, game_change_scene and game_reparent_node. Signals get their own trio: game_connect_signal, game_disconnect_signal and game_emit_signal. The split matters because the two paths have different failure modes. A malformed .tscn edit is a file problem you can diff and revert. A bad game_eval call is code executing inside your running game.

Getting it running: one MCP entry, then project scaffolding from the assistant

The README documents the server as an MCP server, so registration happens in your MCP client's config rather than through a CLI of its own. The material here does not reproduce a full config block, so treat the exact command and argument list as something to read from the repository before you write it. What the README does give is the tool-level workflow. To start a project from nothing, call create_project, and pass dotnet: true to scaffold a .NET project, which the README says produces a .csproj using Godot.NET.Sdk matched to your installed Godot version plus the "C#" feature flag. From there create_csharp_script generates a C# script with a partial class and the correct _Ready and _Process override signatures, keeping the class name in sync with the file name so Godot can attach it. For an existing project, the configuration tools are manage_autoloads (add, remove, list), manage_input_map (add, remove, list actions and key bindings), and manage_export_presets. Diagnostics are validate_script for one file and validate_scripts for all git-changed or project-wide files. get_project_info reports an isDotnet field, which is the cheapest way to confirm the server sees your project as a .NET project before calling anything C#-specific.

The two 3.1 fixes are the most interesting part of the changelog

Two entries in the 3.1 release notes describe bugs that would have been hard to diagnose from the outside. The first concerns validate_script. Previously it used --check-only at _init(), which runs before project autoloads are registered, so any script referencing an autoload singleton produced a false Identifier not found error. The fix compiles the target through a SceneTree at _initialize() instead, after autoloads exist. The README states this was verified by building a full game whose scripts reference several autoloads, and that real syntax and type errors are still caught. That distinction is the useful part: a validator that reports false positives on autoload references is worse than no validator, because you learn to ignore it. The second fix is in manage_input_map. Adding a second key to an existing input action previously wrote a duplicate actionname= line into project.godot, which left the file malformed and silently dropped the earlier binding. The 3.1 behaviour merges the new key into the action's events array with physical_keycode de-duplication. Silent data loss in project.godot is exactly the class of bug that makes people distrust file-rewriting tools, so it is worth knowing which version you are on.

Where it is the wrong tool

The README states the 3.0 line requires Godot 4.4 or later and was tested with 4.7. If your project is on 4.3 or older, this fork is not the version to reach for, regardless of how well the tool list matches what you want to do. The second constraint is the tool count itself. The upstream project had 20 tools, v2.0.0 expanded to 149, and v3.0.0 landed at 157. A surface that grows by roughly an order of magnitude in two major releases is not a stable API, and anything you build on top of specific tool names or argument shapes should be pinned to a version rather than tracking main. Third, the runtime tools are only as safe as the code you send through game_eval. That tool executes arbitrary GDScript in a live game, and nothing in the material suggests a sandbox. If you are pointing this at a project with unsaved editor state or a long-running play session, a bad eval call is not a file you can revert. Finally, the C# path is scaffolding and script generation. The README describes create_project with dotnet: true and create_csharp_script; it does not describe C#-specific diagnostics to match validate_script for GDScript. If your project is C#, expect the validation story to be thinner.

Compared with the upstream godot-mcp it forked from

The honest comparison here is not against some other MCP server, because the README does not name one. It is against Coding-Solo's godot-mcp, which this project explicitly credits for the TypeScript MCP server, the headless GDScript operations system and the TCP runtime interaction server. The difference in approach is scope, not architecture. Upstream offered 20 tools covering basic project management and scene creation. This fork keeps the same three-part design and adds runtime code execution, node inspection and manipulation, signal wiring, animation and tween control, performance and error capture, enhanced input including key hold and release, mouse drag, scroll and gamepad events, project creation with .NET support, and GDScript diagnostics. If you only need to create a project and a scene, upstream is the smaller dependency. If you need to hold a key down for several frames, read FPS and draw calls from a running game, or validate a script that references an autoload, those are additions here and not in the original. The cost of the wider surface is a wider set of things that can behave differently between releases.

Maintenance, licensing and what to verify before committing

The licence is MIT, which is the same permissive family as the upstream project it extends, and the README carries the MIT badge. MIT places few conditions on reuse; the practical obligation is preserving the copyright and permission notice, and you should read the LICENSE file in the repository rather than take a summary from an article, including this one. On maintenance: the release history shows v2.0.0 in March 2026, v3.0.0 in July 2026 and v3.1.0 the same day as the latest push, so the project is moving in large steps rather than small patches. That cadence means upgrade cost is real. Read the release notes before bumping, because the 3.0 and 3.1 entries describe behaviour changes in existing tools, not just additions. The three things worth verifying yourself, in order: scaffold a throwaway project with create_project and dotnet: true and confirm the .csproj SDK version matches your Godot install; run validate_script against a file that references one of your autoloads and confirm it does not report Identifier not found; and add a second key to an existing input action with manage_input_map, then open project.godot and confirm the first binding is still there. Those three checks map directly to the claims the release notes make, and they take a few minutes.

Editorial conclusion

Adopt it if you already drive Godot from a terminal and want an assistant to read and write .tscn files, project.godot and a running game through one MCP surface, and if you are on Godot 4.4 or later. Do not adopt it if you need a stable tool inventory across releases, since the count moved from 20 to 149 to 157 in three releases, or if you are pinned to Godot 4.3 or older. Before wiring it into a project, run create_project with dotnet: true into a throwaway directory to confirm the generated .csproj SDK version matches your installed Godot, and run validate_script on a file that references an autoload to confirm the SceneTree-based check resolves it rather than reporting Identifier not found.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tugcantopaloglu/godot-mcp on GitHub