Open-source project
tugcantopaloglu/godot-mcp avatar
tugcantopaloglu/godot-mcp

godot-mcp gives an agent 157 tools, one of which runs code inside your game

MCP server for full Godot 4.x engine control: 157 tools for AI-driven game development (GDScript and C#/.NET). Tested with Godot 4.7.

514 stars77 forksJavaScriptMIT

At a glance

What is it?
godot-mcp is a Model Context Protocol server that exposes a Godot 4.x project to an AI assistant, extended from a 20-tool original to 157 tools across file editing, headless scene operations and a TCP link into a running game. The architecture is the story, and so is the tool that executes arbitrary GDScript in the live process.
Who is it for?
Adopt godot-mcp if you want an assistant that can read and edit .tscn files, validate GDScript before you run anything, and inspect a live game over a socket, and if you are willing to run that game with an injected server attached.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 37 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • tugcantopaloglu/godot-mcp514 ★ · +58
Star history
Repository2026-09-122026-11-15
tugcantopaloglu/godot-mcp456514

58 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

157 tools is a surface count, and the original had 20

Stated at the top of the README, the fork relationship explains the shape of the project. This builds on and extends `Coding-Solo/godot-mcp` by Solomon Elias, which provided the foundational pieces: the TypeScript MCP server, the headless GDScript operations system, and the TCP-based runtime interaction server. The original offered 20 tools for project management and scene creation. This one offers 157.

Headline number for the project, the tool count is worth reading as a surface measurement rather than a quality one. The release notes show how it moved: v2.0.0 in March 2026 was titled full Godot 4.x coverage with 149 tools, v3.0.0 in July added .NET support, GDScript validation and reached 157, and v3.1.0 landed three days later. That is a large surface added in three releases.

Looking at what the additions mostly are tells you what the fork is for. The overwhelming majority are `game_` prefixed runtime tools, which is a different category from what came before. The original was about files and scenes; this is about a running process.

If you came looking for a way to have an assistant edit scene files, a much smaller tool surface would do it. What you are buying here is live-game debugging, and everything below follows from that.

The honest alternative is no MCP server at all. A Godot project is text: .tscn scenes and .gd scripts are files you can read, diff and edit, and the editor reports errors when you run the project. An assistant can write a scene file without any of this, and you can run the game and read the result yourself. What it cannot do is hold a key down, query a node at runtime, or evaluate an expression in a live process. That gap is what the added tools close, and it is why the count grew rather than the feature set.

Three tiers: files, headless scene edits, and a socket into the running game

Three layers divide the tools, and they behave differently and fail differently.

File access is the bottom layer. `read_file`, `write_file`, `delete_file` and `create_directory` give full file system access within Godot projects, described in those terms rather than scoped to a subdirectory. That scope statement is the thing to notice.

The middle layer needs no running game at all. `read_scene` parses a .tscn and returns the full node tree with properties as JSON, `modify_scene_node` and `remove_scene_node` edit scene files, `attach_script` binds a GDScript file to a node, `create_resource` writes .tres files, and `read_project_settings` and `modify_project_settings` treat project.godot as structured data. These run headlessly, which means an agent can restructure a project while the editor is closed.

The runtime is the top layer, and it is a different mechanism entirely: a TCP-based interaction server inside the running game. Tools like `game_get_property`, `game_set_property`, `game_call_method`, `game_instantiate_scene`, `game_change_scene` and `game_reparent_node` all travel over that socket.

Version 3.0 added something that only matters at the top layer: runtime commands are correlated by request id. Without it, concurrent commands on one socket cannot be matched to their replies, and an agent issuing several operations in sequence gets crossed answers.

game_eval executes arbitrary GDScript inside the running process

One tool deserves to be named on its own. `game_eval` executes arbitrary GDScript code in the running game and returns values, with full `await` support for async code, and it works even when the game is paused because it runs under `PROCESS_MODE_ALWAYS`.

Each clause is a deliberate widening. Async support means the tool can await a signal or a timer rather than forcing synchronous logic. Running while paused means a paused game is still inspectable, which is exactly when you want to look at it.

The combination is what makes the tool useful for debugging and what makes it the one to think about before you wire it up. An assistant that can read properties and call methods has bounded reach. An assistant that can evaluate arbitrary GDScript in your process does not, and it will do so whether or not a human approved that particular expression.

None of this is hidden, and the runtime layer has more of the same shape: `game_get_node_info` returns properties, signals, methods and children for any node, `game_call_method` invokes any method with arguments, and `game_instantiate_scene` adds scenes to the live tree. The blast radius is the same even where the tools look narrower. If the project directory contains anything you would not paste into a chat window, that is the relevant boundary, not the tool count.

The agent can hold a key, drag the mouse and press a gamepad button

Input tools are what make this a testing tool rather than an inspection tool. `game_key_hold` and `game_key_release` hold a key down, which is what you need for movement testing with WASD, where a press-and-release event is indistinguishable from a tap. `game_scroll` sends wheel events, `game_mouse_drag` drags between two points across multiple frames, and `game_gamepad` produces button and axis input.

Synchronisation is frame-based rather than time-based, which is the correct choice inside a game loop. `game_wait` waits N frames, so a sequence like hold a key, wait ten frames, read the player's position is deterministic instead of depending on how long a request happens to take.

Query tools fill out the same loop. `game_get_nodes_in_group` and `game_find_nodes_by_class` let an assistant locate what it needs without being told the node path, and `game_performance` returns FPS, frame time, memory, object counts and draw calls, so a performance claim can be checked against the running process rather than asserted.

Diagnostics are differential too. `game_get_errors` returns new `push_error` and `push_warning` messages since the previous call, and `game_get_logs` returns new print output since the previous call, so polling accumulates rather than repeating.

Physics and audio follow the same pattern. `game_raycast` casts a ray and auto-detects 2D against 3D, and `game_get_audio` reads the audio bus layout.

validate_script moved to _initialize to stop blaming autoloads for syntax errors

The 3.1 release contains the best bug story in the project, and it explains a real constraint of the engine.

Validation used to compile the target with `--check-only` at `_init()`. Autoload singletons are registered later than that, during scene tree initialisation, so any script referring to one produced a false `Identifier not found` error. The fix compiles the script through a `SceneTree` at `_initialize()` instead, after project autoloads are registered. Real syntax and type errors are still caught, and it was verified against a full game whose scripts reference several autoloads.

So a validation false positive was not a bug in the validator. It was the validator running at a moment when the thing being referenced genuinely did not exist yet, which is a distinction worth carrying to any tool that compiles code outside the game.

Its batch version, `validate_scripts`, validates all git-changed .gd files or the whole project, so an assistant can check its own edits before anything runs. It returns `{ valid, errors: [{ message, file, line }] }`, which is structured enough to drive a retry loop.

This is the feature that most directly changes how the tool is used. Without trustworthy validation an agent writes code, runs the game, reads a stack trace and guesses. With it, the loop closes without launching anything.

A duplicate line once left project.godot malformed

The other 3.1 fix is a data-corruption bug, the kind that erodes trust in a tool that edits configuration for you.

`manage_input_map` adds, removes and lists input actions and key bindings. Adding a second key to an action that already existed used to write a duplicate `actionname=` line into project.godot. The result was a malformed configuration file that silently dropped earlier bindings, meaning input you had already set up stopped working with no error explaining why.

Merging is the fix: the new key goes into that action's existing `events` array, with `physical_keycode` de-duplication so adding a binding that is already present is a no-op rather than a second copy.

Merging rather than appending is the correct behaviour for a structured document, and the de-duplication detail suggests the author understood that the file is parsed rather than read. It is also a reminder that `modify_project_settings` and `manage_input_map` write to a file the engine reads at startup, so a malformed write is not a cosmetic problem.

The same release covers correctness fixes across the headless scene operations and the runtime server: resource-typed properties now persist instead of being lost, reparenting works, and the tools survive projects built with warnings treated as errors.

C# scaffolding matches the SDK version to the Godot you have installed

.NET support arrived in 3.0, and the interesting part is that it reads the local install rather than assuming a version.

`create_project` with `dotnet: true` scaffolds a Godot .NET project with a `.csproj` using `Godot.NET.Sdk`, and the SDK version is matched to your installed Godot, plus the `"C#"` feature flag in the project configuration. Getting that pairing wrong is the usual reason a C# Godot project refuses to build, so deriving it is the useful part.

`create_csharp_script` generates a partial class with correct `_Ready` and `_Process` override signatures, and keeps the class name in sync with the file name. That last constraint is not stylistic: Godot attaches a script to a node by matching them, so a class named differently from its file will not attach. `get_project_info` reports an `isDotnet` field so an assistant can tell which of the two languages it is looking at before generating anything.

Moving with the release was the Godot version floor. 3.0 requires Godot 4.4 or later and is tested and working against 4.7. The earlier releases did not carry that floor, so a project pinned to an older engine cannot use the current tools.

Two management tools round out the configuration surface: `manage_autoloads` for the singletons that caused the validation bug above, and `manage_export_presets` for export configuration.

The published package is build/ only, with three runtime dependencies

One aspect of the npm packaging is unusual and worth knowing. The `files` array contains a single entry, `build`, so the tarball ships the compiled output and nothing else. Source, tests and the TypeScript configuration are not in the published package, which means the only thing an installed copy contains is the built server.

The package is `@tugcantopaloglu/godot-mcp` at version 3.1.0, ESM by way of `type: module`, with a single binary entry mapping `godot-mcp` to `./build/index.js`. There is also a `server.json` manifest and an `mcpName` of `io.github.tugcantopaloglu/godot-mcp`, which is the form MCP clients use to identify a server.

Three runtime dependencies is a short list: the MCP SDK pinned to the exact version `1.26.0` rather than a range, plus `axios` and `fs-extra`. Pinning one dependency exactly while leaving the others on carets is a defensible choice for a protocol client and a mild inconsistency. Development uses `vitest` with a config file at the root, and `typescript` at 5.3. The declared engine floor is Node 18 or newer while the type definitions target Node 20.

Trying it without wiring an assistant means building first, since the inspector runs the built file and the build step is `tsc` followed by a repository script:

bash
npx @modelcontextprotocol/inspector build/index.js

A `prepare` script runs the build, so installing straight from a git checkout compiles the TypeScript as a side effect of installation. The repository root carries `CONTRIBUTING.md` and a `.github/` directory but no documentation directory.

The README itself is cut off partway through the audio tools, so the sections covering setup, configuration and the remaining tools are not in the published front page. What is visible ends mid-sentence on the audio bus layout.

Editorial conclusion

Adopt godot-mcp if you want an assistant that can read and edit .tscn files, validate GDScript before you run anything, and inspect a live game over a socket, and if you are willing to run that game with an injected server attached. Do not adopt it as a general editing tool if your workflow is C# only and you cannot accept arbitrary GDScript evaluation inside the process, and do not read 157 as a quality figure, since the count went from 20 in the original to 149 in v2.0.0 and 157 in v3.0.0. Verify three things first: your Godot version, because 3.0 raised the floor to 4.4 and the project is tested against 4.7; whether `game_eval` is reachable in your setup, since it evaluates arbitrary GDScript in the running game and works while paused; and that you have read what `delete_file` and `write_file` are scoped to, since file access is described as full access within Godot projects.

Frequently asked questions

what is godot mcp

It is a Model Context Protocol server that gives an AI assistant control over a Godot 4.x project through 157 tools, covering file access, headless scene operations, and a TCP-based runtime link into a running game. The package is published as @tugcantopaloglu/godot-mcp under the MIT licence, and it extends an earlier project by Coding-Solo that provided 20 tools.

how to install godot mcp

The npm package is @tugcantopaloglu/godot-mcp, whose binary entry is godot-mcp and which declares Node 18 or newer, and it needs Godot 4.4 or later since version 3.0. The build step runs tsc followed by a repository script, and the package publishes only the build directory, so a copy installed from source has to be compiled before it will start.

Does godot-mcp run arbitrary code in my game?

Yes. The game_eval tool executes arbitrary GDScript in the running game with return values, supports await for async code, and works even while the game is paused because it runs under PROCESS_MODE_ALWAYS. Runtime tools can also call any method on any node and instantiate scenes into the live tree.

What Godot version does godot-mcp need?

Version 3.0 requires Godot 4.4 or later and is tested and working against the latest Godot 4.7. The published description also states it was tested with Godot 4.7.

Can godot-mcp validate GDScript without running the game?

Yes. validate_script checks a single file headlessly and returns a valid flag with a list of errors carrying message, file and line, while validate_scripts batch-validates all git-changed .gd files or the whole project. Since 3.1 the check compiles through a SceneTree at _initialize so references to autoload singletons no longer produce false Identifier not found errors.

Does godot-mcp support C# and .NET projects?

Yes, since version 3.0. create_project with dotnet true scaffolds a .csproj using Godot.NET.Sdk with the SDK version matched to your installed Godot plus the C# feature flag, create_csharp_script generates a partial class whose name is kept in sync with the file name, and get_project_info reports an isDotnet field.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. tugcantopaloglu/godot-mcp on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tugcantopaloglu-godot-mcp.svg)](https://hysenlabs.com/projects/tugcantopaloglu-godot-mcp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tugcantopaloglu-godot-mcp.svg)](https://hysenlabs.com/projects/tugcantopaloglu-godot-mcp)

Was this useful?