Skip to content
Back to search

godot-mcp-runtime

A lightweight, zero-footprint TypeScript MCP server that lets AI assistants drive the Godot 4.x game engine.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Erodenn/godot-mcp-runtime with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Erodenn/godot-mcp-runtime'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/erodenn--godot-mcp-runtime/badge.svg)](/listings/erodenn--godot-mcp-runtime)

HTML

<a href="/listings/erodenn--godot-mcp-runtime"><img src="/api/listings/erodenn--godot-mcp-runtime/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- [Node.js](https://nodejs.org/) v20+ - [Godot 4.x](https://godotengine.org/)

That's it. No Godot addon, no project modifications.

Configure Your MCP Client

Add the following to your MCP client config. Works with Claude Code, Claude Desktop, Cursor, or any MCP-compatible client. Ask your AI assistant to call `check_project`. If it returns a Godot version string (e.g., `4.4.stable`), you're connected and working.

**Zero-install via npx (recommended):**

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

**Or install globally:**

npm install -g godot-mcp-runtime
{
  "mcpServers": {
    "godot": {
      "command": "godot-mcp-runtime",
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

**Or clone from source:**

git clone https://github.com/Erodenn/godot-mcp-runtime.git
cd godot-mcp-runtime
npm install
npm run build
{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

> [!TIP] > **Prefer pnpm?** All three install paths work with pnpm. Substitute `pnpm dlx godot-mcp-runtime` for `npx -y godot-mcp-runtime`, `pnpm add -g godot-mcp-runtime` for the global install, or `pnpm install && pnpm run build` for the source build. pnpm ships stronger defaults against npm supply-chain attacks; see [pnpm's supply chain security guide](https://pnpm.io/supply-chain-security).

If Godot is on your `PATH`, you can omit `GODOT_PATH` entirely. The server will auto-detect it.

Optional environment variables

All are set in the same `env` block as `GODOT_PATH`:

| Variable | Effect | | -------- | ------------------------------------------- | | `DEBUG` | `"true"` enables verbose `[DEBUG]` logging. |

The three security-gate flags below share one axis (see [`docs/security.md`](docs/security.md) for the full picture) and are wide enough to wrap badly in a table, so they get a list instead:

- **`GODOT_MCP_DISABLE_ELICITATION`** - `"true"` disables the confirmation prompts for `run_project` and `run_script`. Use this if your client cannot display elicitation prompts (e.g. Claude Desktop, which auto-cancels them). Fail-open: the action proceeds with a warning. Tier 1 security hard-blocks still apply. - **`GODOT_MCP_STRICT`** - `"true"` hard-rejects anything that would otherwise prompt, for unattended operation. Takes precedence over `GODOT_MCP_DISABLE_ELICITATION` when both are set. - **`GODOT_MCP_DISABLE_SECURITY`** - `"true"` turns the entire `run_script`/`run_project` security gate off: no scan, no block, no elicitation, no warnings, no audit sidecars - Tier 1 included. Overrides `GODOT_MCP_STRICT` when both are set. **Enabling this is a human decision - an agent should decline to set it on a user's behalf.**

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>",
        "GODOT_MCP_DISABLE_ELICITATION": "true"
      }
    }
  }
}

> [!IMPORTANT] > **Windows path gotchas.** `GODOT_PATH` must point at the Godot executable itself, not its install folder. Backslashes in JSON must be escaped or replaced with forward slashes: > > ```json > "GODOT_PATH": "D:\\Godot\\Godot_v4.4-stable_win64.exe" > // or equivalently > "GODOT_PATH": "D:/Godot/Godot_v4.4-stable_win64.exe" > ``` > > Setting the variable from a wrapper `.bat` does not propagate to the MCP server - the path must live in the client's `env` block above.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 219 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Godot MCP Runtime
  2. <p align="center">
  3. <a href="https://glama.ai/mcp/servers/@Erodenn/godot-mcp-runtime"><img width="380" height="200" src="https://glama.ai/mcp/servers/@Erodenn/godot-mcp-runtime/badge" alt="godot-mcp-runtime MCP server"></a>
  4. </p>
  5. <p align="center">
  6. <a href="https://modelcontextprotocol.io/introduction"><img src="https://badge.mcpx.dev?type=server" alt="MCP Server"></a>
  7. <a href="https://www.npmjs.com/package/godot-mcp-runtime"><img src="https://img.shields.io/npm/v/godot-mcp-runtime" alt="npm version"></a>
  8. <a href="https://www.npmjs.com/package/godot-mcp-runtime"><img src="https://img.shields.io/npm/dw/godot-mcp-runtime" alt="npm weekly downloads"></a>
  9. <a href="LICENSE"><img src="https://badgen.net/github/license/Erodenn/godot-mcp-runtime" alt="License: MIT"></a>
  10. <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/godot-mcp-runtime" alt="Node.js"></a>
  11. </p>
  12. A lightweight [MCP](https://modelcontextprotocol.io/) server that gives AI agents the tools to interact with the [Godot](https://godotengine.org/) game engine. Features comprehensive headless editing and full runtime control over a Godot 4.x project. Scene, node, autoload, and validation ops cover everything short of the most niche corners of the engine; the runtime bridge adds screenshots, input simulation, UI discovery, and live GDScript against the running scene tree.
  13. <p align="center"><img src="docs/assets/demo.gif" alt="Agent driving a Godot game via MCP runtime tools" width="1000"></p>
  14. <h3 align="center">The AI doesn't just write your game, it can check its work.</h3>
  15. <br>
  16. - **Headless editing**: scenes, nodes, scripts, signals, validation, no editor window
  17. - **Runtime control**: screenshots, input simulation, UI discovery, live GDScript, and profiling (functions, FPS, monitors, render stages) against the running game
  18. - **Zero footprint**: no Godot addon, no project commits, auto-cleanup on shutdown
  19. **No addon required.** Most Godot MCP servers that offer runtime support ship as a Godot addon, something you install into your project, commit to version control, and manage as a dependency. Use npx and there's no install or setup needed.
  20. Think of it as [Playwright MCP](https://github.com/microsoft/playwright-mcp), but for Godot. This does the same thing for games: run the project, take a screenshot, simulate input, read what's on screen, execute a script against the live scene tree. The agent closes the loop on its own changes rather than handing off to you to verify.
  21. > [!NOTE]
  22. > This is not a playtesting replacement. It doesn't catch the subtle feel issues that only a human notices, and it won't tell you if your game is fun. What it does is let an agent confirm that a scene loads, a button responds, a value updated, a script ran without errors. The ability to check work is crucial for AI driven workflows.
  23. ## Contents
  24. - [What It Does](#what-it-does)
  25. - [How It Compares](#how-it-compares)
  26. - [Quick Start](#quick-start)
  27. - [Docs](#docs)
  28. - [Acknowledgments](#acknowledgments)
  29. - [License](#license)
  30. ## What It Does
  31. > This server is the perfect tool kit for AI assisted game development with Godot. It provides a comprehensive suite of tools that allows agents to create scenes, nodes, scripts, and more. The runtime tool set provides the capabilities to check work by running the game and interacting with it in real time, all without becoming a cumbersome dependency on your project.
  32. **Built for agents.** Every tool is purpose-built and self-documenting. When something fails, the response tells the agent how to fix it; when something succeeds, it points toward the next step. The result is an AI that stays unstuck and self-corrects without needing you to nudge it along. All 43 tools return one JSON object with a declared output schema, and a value the server could not measure comes back as `null` with a warning rather than a made-up number.
  33. **Headless editing.** Create scenes, add nodes, set properties, attach scripts, connect signals, validate GDScript. All the standard operations, no editor window required.
  34. **Runtime bridge.** When `run_project` is called, the server injects `McpBridge` as an autoload. This opens a localhost-only TCP listener (a free port is auto-selected when `bridgePort` is omitted; pass `bridgePort` to pin a specific port) and enables:
  35. - **Screenshots:** Capture the viewport. By default this returns a 960x540 preview inline plus the full PNG on disk, and every call also returns pixel statistics (`stats`, with a `likelyBlank` verdict) measured from the full PNG, so a caller that cannot look at the image can still tell a rendered frame from a blank one
  36. - **Input simulation:** Batched sequences of key presses, mouse clicks, mouse motion, UI element clicks by name or path, Godot action events, text typed into the focused Control, and timed waits. Each action reports what it did: the Control it hit, the signals it fired, and what changed on screen
  37. - **UI discovery:** Walk the live scene tree and collect every visible Control node with its position, type, text content, and disabled state
  38. - **Live script execution:** Compile and run arbitrary GDScript with full SceneTree access while the game is running
  39. - **Profiling:** With `profiling: true` at launch, capture Godot's own profiler and rank the most expensive GDScript functions by own or inclusive time, with source locations and per-frame averages. Every capture also reports FPS, frames over a target frame rate, and engine monitors (draw calls, memory, node counts); `visual: true` adds the Visual Profiler's CPU and GPU time per render stage, and `timeline: true` the same over time, with the player position (`track`) on each interval, to find where a walk through the level drops frames
  40. **Background mode.** Pass `background: true` to `run_project` and the Godot window is never shown on Windows; on other platforms it is moved off-screen (positioned at `(-9999, -9999)`) after startup. Mouse input passes through the window. It does not guarantee the game never takes keyboard focus. Programmatic input, screenshots, and all runtime tools work exactly the same. Useful for automated agent-driven testing where the window shouldn't be visible or interactive.
  41. **Manual attach mode.** When something other than MCP launches the game (a CI pipeline, an external debugger, your own shell), call `run_project` with `attach: true` first. It injects the bridge and marks the project active without spawning Godot, so when you launch the game manually, runtime tools work against it. Call `stop_project` when done: it removes the bridge and leaves your Godot process running.
  42. **Render check.** `render_movie` renders a fixed number of frames in a separate short Godot run under the engine's movie writer and reports what rendered: blank or not, moving or not. It injects no bridge, simulates no input and starts no session, so it works as a cheap checkpoint before a full `run_project`. It needs a display, asks for the same launch confirmation as `run_project`, and is refused while a runtime session is live on the same project.
  43. **Several projects at once.** `run_project` on a second project adds a session instead of ending the first, which helps when a game and a small repro project run side by side. The runtime tools act on the current session and name it in every response as `projectPath`; `switch_project` moves them to another one. Nothing falls back silently: if the current session ends, the next call errors and lists the sessions still live. The server runs one runtime operation at a time, so calls issued in parallel wait their turn instead of interleaving.
  44. > [!IMPORTANT]
  45. > `get_debug_output` has nothing to return in attached mode. stdout and stderr only flow through processes MCP started itself, so for an externally launched Godot its `output`, `errors` and `running` are `null` with a warning, never empty lists. Let `run_project` spawn the game if you need the debug stream.
  46. The bridge cleans itself up automatically - on `stop_project`, and also without a tool call when the game exits on its own, the bridge connection drops, or the server shuts down (including a client that just closes the connection). A game the server spawned also quits by itself within a few seconds if the server process is killed outright, and removes the autoload entry from `project.godot` on its way out. Its artifacts live under `.mcp/godot-runtime/` in the project, which the server adds to `.gitignore`. No leftover autoloads, no modified project files.
  47. ## How It Compares
  48. The Godot MCP space splits on two axes: whether a server can drive a _running_ game (runtime) or only edit files, and what it costs your project to do so. Most servers that offer real runtime control ship as a Godot addon you install and commit to version control, or as a custom engine you download. This one injects a bridge transiently and removes it on shutdown, so you get full live-game control against stock Godot with nothing left in your repo.
  49. | Server | Live-game runtime | Footprint | License | Price |
  50. | ------------------------- | ---------------------------------------------------------- | ------------------------------------ | ------------------------------ | --------------------- |
  51. | **Godot MCP Runtime** | **Full**: screenshots, input, live scene tree, script exec | **Zero** (`npx`, no committed addon) | MIT | Free |
  52. | Summer Engine | Full | Custom engine download + sign-in | MIT layer / proprietary engine | Free core, paid cloud |
  53. | tugcantopaloglu/godot-mcp | Full | Committed autoload addon | MIT | Free |
  54. | Godot MCP Pro | Full | Committed editor addon | Proprietary | $15 |
  55. | GDAI MCP | Editor-mediated | Committed editor addon | Proprietary | $19 |
  56. | Coding-Solo/godot-mcp | No (launch + debug output) | Zero (`npx`) | MIT | Free |
  57. Among servers with full live-game control, Godot MCP Runtime pairs a zero-footprint install (no addon committed to version control, no custom engine, no account) with a single `npx` command, and it has shipped this transient-autoload runtime bridge since February 2026. For the full field of ~20 servers with a source for every claim, see [docs/comparison.md](docs/comparison.md).
  58. ## Quick Start
  59. ### Prerequisites
  60. - [Node.js](https://nodejs.org/) v20+
  61. - [Godot 4.5 or later](https://godotengine.org/)
  62. That's it. No Godot addon, no project modifications.
  63. ### Configure Your MCP Client
  64. Add the following to your MCP client config. Works with Claude Code, Claude Desktop, Cursor, or any MCP-compatible client.
  65. Ask your AI assistant to call `check_project`. If it returns a Godot version string (e.g., `4.5.stable`), you're connected and working.
  66. **Zero-install via npx (recommended):**
  67. ```json
  68. {
  69. "mcpServers": {
  70. "godot": {
  71. "command": "npx",
  72. "args": ["-y", "godot-mcp-runtime"],
  73. "env": {
  74. "GODOT_PATH": "<path-to-godot-executable>"
  75. }
  76. }
  77. }
  78. }
  79. ```
  80. **Or install globally:**
  81. ```bash
  82. npm install -g godot-mcp-runtime
  83. ```
  84. ```json
  85. {
  86. "mcpServers": {
  87. "godot": {
  88. "command": "godot-mcp-runtime",
  89. "env": {
  90. "GODOT_PATH": "<path-to-godot-executable>"
  91. }
  92. }
  93. }
  94. }
  95. ```
  96. **Or clone from source:**
  97. ```bash
  98. git clone https://github.com/Erodenn/godot-mcp-runtime.git
  99. cd godot-mcp-runtime
  100. npm install
  101. npm run build
  102. ```
  103. ```json
  104. {
  105. "mcpServers": {
  106. "godot": {
  107. "command": "node",
  108. "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
  109. "env": {
  110. "GODOT_PATH": "<path-to-godot-executable>"
  111. }
  112. }
  113. }
  114. }
  115. ```
  116. > [!TIP]
  117. > **Prefer pnpm?** All three install paths work with pnpm. Substitute `pnpm dlx godot-mcp-runtime` for `npx -y godot-mcp-runtime`, `pnpm add -g godot-mcp-runtime` for the global install, or `pnpm install && pnpm run build` for the source build. pnpm ships stronger defaults against npm supply-chain attacks; see [pnpm's supply chain security guide](https://pnpm.io/supply-chain-security).
  118. If Godot is on your `PATH`, you can omit `GODOT_PATH` entirely. The server will auto-detect it.
  119. ### Optional environment variables
  120. All are set in the same `env` block as `GODOT_PATH`:
  121. | Variable | Effect |
  122. | -------- | ------------------------------------------- |
  123. | `DEBUG` | `"true"` enables verbose `[DEBUG]` logging. |
  124. - **`GODOT_MCP_DISABLE_ELICITATION`** - `"true"` skips the confirmation prompts for the first `run_project` launch, `render_movie` and `run_script` on a project. Use this if your client cannot display elicitation prompts (e.g. Claude Desktop, which auto-cancels them). The action proceeds with a warning.
  125. ```json
  126. {
  127. "mcpServers": {
  128. "godot": {
  129. "command": "npx",
  130. "args": ["-y", "godot-mcp-runtime"],
  131. "env": {
  132. "GODOT_PATH": "<path-to-godot-executable>",
  133. "GODOT_MCP_DISABLE_ELICITATION": "true"
  134. }
  135. }
  136. }
  137. }
  138. ```
  139. > [!IMPORTANT]
  140. > **Windows path gotchas.** `GODOT_PATH` must point at the Godot executable itself, not its install folder. Backslashes in JSON must be escaped or replaced with forward slashes:
  141. >
  142. > ```json
  143. > "GODOT_PATH": "D:\\Godot\\Godot_v4.5-stable_win64.exe"
  144. > // or equivalently
  145. > "GODOT_PATH": "D:/Godot/Godot_v4.5-stable_win64.exe"
  146. > ```
  147. >
  148. > Setting the variable from a wrapper `.bat` does not propagate to the MCP server - the path must live in the client's `env` block above.
  149. ### Security
  150. The server does not sandbox anything. A launched project and `run_script` run with your user permissions, and the server asks you to confirm once per project per session before the first of each. [`SECURITY.md`](SECURITY.md) lists what runs code, what the agent can change and how to report a vulnerability.
  151. ## Docs
  152. - [`docs/tools.md`](docs/tools.md): full tool reference, grouped by category
  153. - [`docs/tool-authoring.md`](docs/tool-authoring.md): standards for adding or modifying tools
  154. - [`docs/architecture.md`](docs/architecture.md): source layout, bridge sequence diagram, lifecycle steps, runtime artifact behavior
  155. - [`SECURITY.md`](SECURITY.md): trust model, what runs code, what the confirmation prompts cover, how to report a vulnerability
  156. - [`docs/migration-4.0.md`](docs/migration-4.0.md): every breaking change from 3.8.1 to 4.0, with its before and after
  157. ## Acknowledgments
  158. Built on the foundation laid by [Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp) for headless Godot operations.
  159. Developed with [Claude Code](https://claude.ai/code).
  160. ## License
  161. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.