tugcantopaloglu/godot-mcp: 157 MCP tools for driving Godot 4.x from an AI assistant

The gap this fork fills in the original godot-mcp

The upstream project, Coding-Solo/godot-mcp by Solomon Elias, ships 20 tools for basic project management and scene creation. This fork keeps that architecture (TypeScript MCP server, headless GDScript operations, TCP runtime bridge) and expands the surface to 157 tools. The README frames the additions as four groups: runtime code execution and node manipulation, signal and animation control, headless scene and resource editing, and project scaffolding including .NET.

The intended user is an engineer who already works inside an MCP-capable assistant and wants the assistant to touch a real Godot project rather than paste GDScript into a chat window. That is a narrower audience than "Godot developers" in general. If you are not using an MCP client, none of the 157 tools are reachable.

The version history matters here. v2.0.0 (2026-03-02) reached 149 tools. v3.0.0 (2026-07-10) added .NET/C# support and GDScript diagnostics. v3.1.0 (2026-07-13) is the current release and fixes two concrete bugs rather than adding tools. The last push was on 2026-07-13.

Two execution paths: headless GDScript and a TCP runtime bridge

The architecture splits cleanly along whether a game is running.

Headless operations do not need a live process. read_scene parses a .tscn file and returns the node tree with properties as JSON. modify_scene_node, remove_scene_node and attach_script edit those files. create_resource writes .tres files. read_project_settings and modify_project_settings parse and rewrite project.godot. These run through the headless GDScript operations system inherited from the upstream project.

Runtime operations go through a TCP-based interaction server inside the running game. game_eval executes arbitrary GDScript in the live process and returns values, with await support and PROCESS_MODE_ALWAYS so it still works while the game is paused. game_get_property, game_set_property, game_call_method and game_get_node_info cover introspection and mutation. Signals have their own trio: game_connect_signal, game_disconnect_signal, game_emit_signal. Timing-sensitive work gets game_wait, which waits N frames.

One detail worth noting: the v3.0.0 notes say runtime commands are now correlated by request id. That implies the earlier design could not reliably match a response to its request, which is a real correctness problem for any tool that fires concurrent commands at a live game.

Error and log capture is split too. game_get_errors returns push_error and push_warning messages since the last call; game_get_logs returns print output since the last call. Both are delta-based, so an assistant that polls irregularly may miss messages between calls.

Installing godot-mcp and running a first validation

The package is published as @tugcantopaloglu/godot-mcp and declares a godot-mcp binary pointing at ./build/index.js. Node 18 or later is required. The repository scripts include a build step (tsc plus a node script) and a prepare hook that runs the build, so installing from the repository compiles TypeScript.

Clone the repository and build it:

git clone https://github.com/tugcantopaloglu/godot-mcp.git
cd godot-mcp
npm install
npm run build

npm install triggers the prepare script, which runs npm run build again. The compiled entry point lands at build/index.js.

To check the server in isolation before wiring it into an assistant, the package defines an inspector script that launches the MCP inspector against the build output:

npm run inspector

That runs npx @modelcontextprotocol/inspector build/index.js and gives you a UI for listing and calling tools. This is the fastest way to confirm the server starts and that all 157 tools register.

For a first real use, pick something that does not need a running game. validate_script compiles a target script through a SceneTree at _initialize(), after project autoloads are registered, instead of using --check-only at _init(). The v3.1.0 notes give the reason: autoload singleton references previously produced false Identifier not found errors. There is also validate_scripts, which the README describes as covering all git-changed files or the whole project. Note that v3.0.0 states Godot 4.4 or later is required, and the project is tested with 4.7.

What the 157-tool count does not tell you

Tool count is a poor proxy for coverage, and this README invites the mistake. Several entries are thin wrappers: read_file, write_file, delete_file and create_directory are filesystem operations scoped to the project. Others are grouped families where the count inflates quickly, such as the input tools (game_key_hold, game_key_release, game_scroll, game_mouse_drag, game_gamepad) and the runtime node tools.

A more useful question is which tools depend on a live game. Everything prefixed game_ needs the TCP bridge and a running process. Everything else works on files. If your workflow is "generate a project, generate scenes, never launch the game," a large fraction of the 157 tools are dead weight in your assistant's tool list, and a long tool list costs context on every turn.

The README also does not document rollback. modify_scene_node, modify_project_settings and manage_input_map write to project files, and there is no described undo, backup or dry-run mode. The v3.1.0 note about manage_input_map is instructive: before the fix, adding a second key to an existing action wrote a duplicate actionname= line, which the notes say left project.godot malformed and silently dropped earlier bindings. That is the failure mode of file mutation without a transaction. Version control is your rollback.

manage_input_map and the merging fix

The manage_input_map change in v3.1.0 deserves its own look because it shows what the tool actually writes. Before the fix, adding a second key to an existing input action appended a duplicate actionname= line instead of merging into the action's events array. The result was a malformed project.godot and lost bindings.

After the fix, a second key merges into that action's events array with physical_keycode de-duplication. If you have ever hand-edited the [input] section of project.godot, you know the format is unforgiving: each action is a dictionary with a deadzone and an events array of InputEventKey objects carrying physical_keycode values. A tool that appends instead of merging corrupts the file in a way that Godot may still load, which is worse than a hard failure.

The practical takeaway is to pin your version. If you are on v3.0.0 or earlier and your assistant calls manage_input_map on an action that already has bindings, you are exposed to exactly this bug. The fix landed in v3.1.0 on 2026-07-13.

The same release fixed validate_script autoload resolution. Both fixes are the kind that only surface on real projects: a script that references an autoload singleton, or an input action with two keys. Neither is exotic.

C# support and where the .NET path stops

v3.0.0 added .NET support. create_project accepts dotnet: true and scaffolds a Godot .NET project with a .csproj using Godot.NET.Sdk matched to your installed Godot version, plus the "C#" feature flag. create_csharp_script generates a C# script with a partial class and the correct _Ready and _Process override signatures, and the README states the class name is kept in sync with the file name so Godot can attach it. get_project_info reports an isDotnet field.

That is scaffolding, not C# tooling parity. GDScript diagnostics have validate_script and validate_scripts. The README does not describe an equivalent validator for C# scripts, so a C# project gets project creation and script generation but not the same compile-check loop. If your reason for choosing this server is the diagnostics workflow, the C# path is thinner than the GDScript path, and the README is silent on how far it goes.

The .NET additions also raise the floor on the toolchain: a C# Godot project needs the .NET SDK in addition to Godot itself, and the .csproj SDK version is tied to your Godot install. Mismatch there is a setup problem this server will not diagnose for you.

godot-mcp versus driving the Godot CLI directly

The obvious alternative is the Godot command line itself. Godot can run headless, import assets, export builds and execute scripts via --headless and --script. If your goal is a build step in CI, the CLI is the right tool: it is one binary, it has no server process, and it does not depend on an MCP client being connected.

The difference in approach is state. The CLI is stateless per invocation: you run a command, you get output, you exit. godot-mcp keeps a persistent TCP bridge into a running game, which is what makes game_eval, game_get_property and game_set_property possible at all. You cannot inspect a live node tree's current property values from a one-shot CLI call, because there is no live process to inspect.

So the split is not about capability but about whether you need a running game. For asset import, export presets and CI builds, use the CLI. For "the player is stuck at this coordinate, read the position and the collision state," you need something attached to the process, and that is the niche this server occupies.

A second alternative is the upstream Coding-Solo/godot-mcp, which this fork extends. If 20 tools cover your needs, the original is a smaller dependency with the same foundational architecture, and the README credits it for the TypeScript server, the headless GDScript system and the TCP runtime server.

Licence, upgrade cost and what to check before adopting

The licence is MIT, declared in package.json and present as a LICENSE file at the repository root. MIT permits commercial use and modification with attribution and without a warranty. That is a permissive choice consistent with the upstream project it forks, and the README maintains an acknowledgments section crediting Solomon Elias and Coding-Solo/godot-mcp. If you fork this further, keep that attribution intact. This is a description of the licence text, not legal advice; read the LICENSE file yourself.

Upgrade cost is moderate. The tool surface grew from 20 to 149 to 157 across three major versions, and each major release changed behaviour rather than only adding tools. v3.0.0 requires Godot 4.4 or later, so anyone on 4.3 cannot upgrade past v2.0.0. v3.1.0 changed how validate_script resolves autoloads and how manage_input_map merges events, both of which alter output an assistant might depend on.

The maintenance picture: the repository is not archived, and the last push was on 2026-07-13, which is the same day v3.1.0 was released. The project has a tests/ directory, a vitest.config.ts and a test script, so there is a test suite you can run with npm test before trusting a local build. server.json is present at the root, which suggests registry metadata for MCP server distribution.

What to verify first: that your assistant connects over stdio to build/index.js, that your Godot binary is discoverable by the server, and that validate_script on a script referencing an autoload returns clean on your project. The last one is the specific regression v3.1.0 claims to fix, and it is the cheapest way to confirm you are on the fixed version.

Editorial conclusion

Adopt tugcantopaloglu/godot-mcp if you already drive Godot 4.4+ from an MCP-capable assistant and want both file-level scene edits and live runtime inspection from one server. Skip it if you are on Godot 4.3 or earlier, or if you only need to open the editor and run the game yourself. Before committing, verify that your assistant connects over stdio, that your Godot binary path is discoverable, and that validate_script stops reporting false Identifier not found errors on your autoload singletons.

Frequently asked questions

Official sources

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