Skip to content
Back to search

godot-mcp

Give your AI assistant eyes and hands in the Godot editor: scene editing, input injection, deterministic playtesting, and live game state for agents

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/satelliteoflove/godot-mcp 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/satelliteoflove/godot-mcp'

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/satelliteoflove--godot-mcp/badge.svg)](/listings/satelliteoflove--godot-mcp)

HTML

<a href="/listings/satelliteoflove--godot-mcp"><img src="/api/listings/satelliteoflove--godot-mcp/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.

1. Configure your AI assistant

Add godot-mcp to your MCP client. See the [Installation Guide](INSTALL.md) for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more). The short version:

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

2. Install the Godot addon

npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project

Enable it in Godot: **Project > Project Settings > Plugins > Godot MCP**

3. Start building

Open your Godot project, restart your AI assistant, and start building. If anything refuses to connect, the [Troubleshooting Guide](docs/troubleshooting.md) has you covered.

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 · 160 lines

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

  1. # godot-mcp
  2. [![npm version](https://img.shields.io/npm/v/%40satelliteoflove%2Fgodot-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/@satelliteoflove/godot-mcp)
  3. [![CI](https://github.com/satelliteoflove/godot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/satelliteoflove/godot-mcp/actions/workflows/ci.yml)
  4. [![Godot 4.5+](https://img.shields.io/badge/Godot-4.5%2B-478cbf?logo=godotengine&logoColor=white)](https://godotengine.org)
  5. [![Node 20+](https://img.shields.io/badge/Node-20%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
  6. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/satelliteoflove/godot-mcp/blob/main/LICENSE)
  7. Give your AI assistant eyes and hands in the Godot editor — and a running game it can actually playtest.
  8. <!-- HERO PLACEHOLDER: short demo GIF goes here (agent running the game, stepping time, reading state). Use an absolute raw.githubusercontent.com URL so it also renders on npm. -->
  9. ## Why this one?
  10. There are a few Godot MCP servers out there, and most can open a scene and poke at nodes. This one is built around a harder problem: **letting an agent verify its own work.** Run the game, drive it like a player, observe what actually happened, and prove the change did what it claimed — without you ferrying screenshots and error logs back and forth.
  11. The pieces that make that possible, and that you won't find elsewhere:
  12. - **Deterministic playtesting.** Freeze the game clock, step exact slices of game time (or step *until a condition holds*), with inputs riding inside the window. Observation never races the game.
  13. - **Cheap observation.** Live entity state — positions, velocities, animation state, your own custom data — as structured JSON. Most "what's happening on screen?" questions get answered without spending vision tokens on a screenshot.
  14. - **Real input.** Named actions with analog strength, joypad buttons and stick vectors, raw keys with modifier combos, relative mouse-look, text typing. Sequences run with precise timing and can prove they changed game state.
  15. - **Scenario setup.** Run GDScript inside the running game: grant the weapon, skip to wave 3, spawn a test bot — no debug hooks baked into your game code.
  16. Here's what that looks like when an agent tests a boss fight:
  17. ```text
  18. godot_editor_edit run frozen=true # boot with game time frozen at frame 0
  19. godot_exec GameState.wave = 3 # set up the scenario worth testing
  20. godot_game_time step_until "tree.get_nodes_in_group('boss').size() >= 1"
  21. godot_runtime_state digest # exact positions and state — no pixels, no guessing
  22. godot_game_time step 500ms + dodge input # play the moment that matters
  23. godot_editor_read screenshot_game # and a screenshot when it's actually worth the tokens
  24. ```
  25. Less copy-paste, more creating.
  26. ## Quick Start
  27. ### 1. Configure your AI assistant
  28. Add godot-mcp to your MCP client. See the [Installation Guide](INSTALL.md) for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more). The short version:
  29. ```json
  30. {
  31. "mcpServers": {
  32. "godot-mcp": {
  33. "command": "npx",
  34. "args": ["-y", "@satelliteoflove/godot-mcp"]
  35. }
  36. }
  37. }
  38. ```
  39. ### 2. Install the Godot addon
  40. ```bash
  41. npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project
  42. ```
  43. Enable it in Godot: **Project > Project Settings > Plugins > Godot MCP**
  44. ### 3. Start building
  45. Open your Godot project, restart your AI assistant, and start building. If anything refuses to connect, the [Troubleshooting Guide](docs/troubleshooting.md) has you covered.
  46. ## What's in the box
  47. 21 tools, 86 actions. Full API docs in the [Tools Reference](docs/tools/README.md).
  48. | Tool | What it does |
  49. |------|--------------|
  50. | `godot_scene` | Open and save scenes (create new scenes by writing the `.tscn` directly, then open) |
  51. | `godot_node_read` / `godot_node_edit` | Inspect effective properties, the full scene tree (including instanced sub-scenes), and find nodes; update properties and reparent |
  52. | `godot_editor_read` / `godot_editor_edit` | Editor state, selection, screenshots, editor error log; run/stop/restart and 2D viewport control |
  53. | `godot_project` | Project info, settings, addon version skew, and stale-settings detection |
  54. | `godot_animation_read` / `godot_animation_edit` | Query animations down to keyframes; author tracks and keyframes with instant editor preview |
  55. | `godot_tilemap_read` / `godot_tilemap_edit` | Read and edit TileMapLayer cells (base64-encoded in `.tscn` — the bridge is the only way) |
  56. | `godot_gridmap_read` / `godot_gridmap_edit` | Read and edit GridMap cells, same story |
  57. | `godot_resource` | Inspect resources with type-aware output: SpriteFrames, TileSet, Materials, Textures |
  58. | `godot_scene3d` | Engine-computed 3D transforms, bounding boxes, and visibility for spatial reasoning |
  59. | `godot_docs` | Fetch Godot documentation as clean markdown, version-matched to your editor |
  60. | `godot_input` | Inject input into the running game: actions, joypad, raw keys, mouse-look, text |
  61. | `godot_profiler` | Metric snapshots and per-frame time series with spike detection |
  62. | `godot_runtime_state` | Live game state as JSON: one-shot digests, watch windows, signal timelines |
  63. | `godot_game_time` | Freeze, step, and step-until on the game clock — deterministic observation |
  64. | `godot_exec` | Run GDScript inside the running game for test scenario setup |
  65. | `godot_validate_meshes` | Detect silently corrupt procedural mesh data that masquerades as lighting bugs |
  66. A note on shape: tools split along the read/write boundary, so every `godot_*_read` tool (and the other read-only tools) can be safely auto-allowed in your client's permission settings while writes stay gated. Related operations still live as actions inside one tool, so your agent's context isn't flooded with definitions it won't use. Anything an agent can do by editing project files directly — creating scenes and nodes, attaching scripts, connecting signals — is deliberately *not* duplicated as a tool; the bridge covers what files can't: editor state, verification, binary-encoded cell data, and the running game. A `--read-only` flag serves the look-but-don't-touch use case.
  67. ## Things to ask for
  68. A feel for what an agent can do with this, in plain prompts:
  69. - *"Run the game and screenshot the title screen. Does the layout survive 1280x720?"*
  70. - *"The player can clip through the east wall. Reproduce it, then check the collision shapes and tell me why."*
  71. - *"Step the game until the second wave spawns and give me every enemy's position and velocity."*
  72. - *"Hold the left stick at half deflection for two seconds — does the walk animation blend correctly?"*
  73. - *"Profile ten seconds of gameplay and find what's causing the frame spikes."*
  74. - *"Add a hit-flash animation to the Player: modulate to red and back over 0.2 seconds."*
  75. For richer runtime observation, add key nodes to the `mcp_watch` group or give them a `_mcp_state()` method — see the [Runtime State Guide](docs/runtime-state-guide.md).
  76. ## How it works
  77. ```text
  78. ┌─────────────────┐ stdio ┌─────────────────┐ WebSocket ┌──────────────────┐ debugger ┌──────────────┐
  79. │ MCP client │ ◄────────► │ godot-mcp │ ◄──────────► │ Bridge addon │ ◄─────────► │ Running game │
  80. │ (Claude, etc.) │ │ server (Node) │ :6550 │ (Godot editor) │ wire │ (autoload) │
  81. └─────────────────┘ └─────────────────┘ └──────────────────┘ └──────────────┘
  82. ```
  83. The server talks to an editor addon over a local WebSocket; the addon reaches into the running game over Godot's own debugger protocol, so the game process needs no extra ports or setup. The addon binds to `127.0.0.1` by default. WSL2 is fully supported (auto-detection, host IP discovery, configurable bind modes) — see the [Installation Guide](INSTALL.md#wsl-support).
  84. Curious about connection lifecycles, the single-client policy, or how frozen-time stepping works under the hood? The [Architecture Guide](docs/architecture.md) goes deep.
  85. ## Works well with minimal-godot-mcp
  86. [minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) by [@ryanmazzolini](https://github.com/ryanmazzolini) covers exactly what this server doesn't: LSP diagnostics for fast static GDScript checking, and the running game's console output over DAP. This server covers everything that needs an editor bridge. No overlap, no conflict — run both, and your agent gets static analysis and the game console alongside full editor and runtime control.
  87. One caveat: a Godot editor serves a single godot-mcp client at a time. Extra clients (a subagent inheriting your MCP config, say) wait their turn rather than hijacking your session — details in [Troubleshooting](docs/troubleshooting.md#one-client-at-a-time).
  88. ## Documentation
  89. - [Installation Guide](INSTALL.md) — MCP client configs for Claude Desktop, Claude Code, VSCode/Copilot, and more
  90. - [Migrating to v4](docs/migrating-to-v4.md) — renamed tools, removed actions, allowlist updates
  91. - [Troubleshooting](docs/troubleshooting.md) — connection checklist, CLI smoke test, common fixes
  92. - [Claude Code Setup Guide](docs/claude-code-setup.md) — CLAUDE.md template for Godot projects
  93. - [Runtime State Guide](docs/runtime-state-guide.md) — expose game state to agents via `mcp_watch` and `_mcp_state()`
  94. - [Tools Reference](docs/tools/README.md) — all 21 tools with full API docs
  95. - [Architecture Guide](docs/architecture.md) — how the server, addon, and game bridge fit together
  96. - [Contributing](CONTRIBUTING.md) — dev setup, adding tools, release process
  97. - [Changelog](server/CHANGELOG.md) — release history
  98. ## Requirements
  99. - **Godot 4.5+** (the addon uses the Logger class introduced in 4.5)
  100. - **Node.js 20+**
  101. - Any MCP client that speaks stdio
  102. ## Development
  103. ```bash
  104. cd server
  105. npm install && npm run build
  106. npm test # unit + schema-snapshot tests
  107. npm run test:protocol # wire-level smoke of the built server
  108. npm run generate-docs
  109. ```
  110. There is also an agentic eval harness (`npm run eval`) that runs realistic
  111. tasks through headless Claude Code against a real project — see
  112. [server/evals/README.md](server/evals/README.md). It never starts Godot; you
  113. bring the open editor.
  114. Contributions welcome — this project favors tools that solve real, time-wasting problems. Read [CONTRIBUTING.md](CONTRIBUTING.md) before building something big, or open an issue and we'll figure out the right shape together.
  115. ## License
  116. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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