Skip to content
Back to search

godot-mcp

MCP Server and Godot Plugin for AI-assisted game development

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

0. Install Node.js (one-time setup)

Download and run the installer from **[nodejs.org](https://nodejs.org/en/download)** (LTS version). It's a standard installer — no terminal needed.

1. Install the Godot plugin

Inside the Godot editor, click the **AssetLib** tab at the top → search **"mcp"** → find **"Godot AI Assistant tools MCP"** → Install.

Then go to **Project → Project Settings → Plugins** and enable the **Godot MCP** plugin.

2. Add the server config to your AI client

**Claude Desktop** — Settings → Developer → Edit Config → open the config file and paste:

Mac / Linux:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-server"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "godot-mcp-server"]
    }
  }
}

**Cursor** — Settings → MCP → Add Server:

Mac / Linux:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-server"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "godot-mcp-server"]
    }
  }
}

**Claude Code** — run in terminal:

claude mcp add godot -- npx -y godot-mcp-server

Works with any MCP-compatible client (Cline, Windsurf, etc.)

3. Restart your AI client

Close and reopen Claude Desktop / Cursor / your client so it picks up the new config.

4. Restart your Godot project

Hit **Restart Project** in the Godot editor. Check the **top-right corner** — you should see **MCP Connected** in green. You're ready to go.

---

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 · 200 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
  2. **Give your AI assistant full access to the Godot editor.**
  3. Build games faster with Claude, Cursor, or any MCP-compatible AI — no copy-pasting, no context switching. AI reads, writes, and manipulates your scenes, scripts, nodes, and project settings directly.
  4. > Godot 4.4+ · 69 tools · Undo/redo · Interactive project visualizer · MIT license
  5. **Now on the [Godot Asset Store](https://store.godotengine.org/asset/tomer-yud/godlink/) as Godlink MCP.** If it helps you, please leave a review there. It's the main way other Godot developers find it.
  6. ![An AI agent in Cursor building a platformer level in the Godot editor](screenshots/agent-building-level.webp)
  7. ---
  8. ## Quick Start
  9. ### 0. Install Node.js (one-time setup)
  10. Download and run the installer from **[nodejs.org](https://nodejs.org/en/download)** (LTS version). It's a standard installer — no terminal needed.
  11. ### 1. Install the Godot plugin
  12. **Godot 4.7 and newer:** inside the Godot editor, click the **Asset Store** tab at the top → search **"Godlink"** → find **"Godlink MCP"** → Install. ([Store page](https://store.godotengine.org/asset/tomer-yud/godlink/))
  13. **Godot 4.6 and older:** click the **AssetLib** tab instead → search **"mcp"** → find **"Godot AI Assistant tools MCP"** → Install.
  14. **Manual install:** copy the `addons/godot_mcp/` folder from this repo into your project's `addons/` folder.
  15. Then go to **Project → Project Settings → Plugins** and enable the **Godot MCP** plugin.
  16. ### 2. Add the server config to your AI client
  17. **Claude Desktop** — Settings → Developer → Edit Config → open the config file and paste:
  18. Mac / Linux:
  19. ```json
  20. {
  21. "mcpServers": {
  22. "godot": {
  23. "command": "npx",
  24. "args": ["-y", "godot-mcp-server"]
  25. }
  26. }
  27. }
  28. ```
  29. Windows:
  30. ```json
  31. {
  32. "mcpServers": {
  33. "godot": {
  34. "command": "cmd",
  35. "args": ["/c", "npx", "-y", "godot-mcp-server"]
  36. }
  37. }
  38. }
  39. ```
  40. **Cursor** — Settings → MCP → Add Server:
  41. Mac / Linux:
  42. ```json
  43. {
  44. "mcpServers": {
  45. "godot": {
  46. "command": "npx",
  47. "args": ["-y", "godot-mcp-server"]
  48. }
  49. }
  50. }
  51. ```
  52. Windows:
  53. ```json
  54. {
  55. "mcpServers": {
  56. "godot": {
  57. "command": "cmd",
  58. "args": ["/c", "npx", "-y", "godot-mcp-server"]
  59. }
  60. }
  61. }
  62. ```
  63. **Claude Code** — run in terminal:
  64. ```bash
  65. claude mcp add godot -- npx -y godot-mcp-server
  66. ```
  67. Works with any MCP-compatible client (Cline, Windsurf, etc.)
  68. ### 3. Restart your AI client
  69. Close and reopen Claude Desktop / Cursor / your client so it picks up the new config.
  70. ### 4. Restart your Godot project
  71. Hit **Restart Project** in the Godot editor. Check the **top-right corner** — once your AI client is running you should see **MCP: Agent Active** in green. You're ready to go.
  72. If it shows **MCP: No Agent** in orange, Godot found the server but no AI client is using it yet. Restart your AI client. **MCP: Disconnected** in red means the server isn't running. Check that Node.js is installed and the config from step 2 is saved.
  73. ---
  74. ## What Can It Do?
  75. ### 69 Tools Across 7 Categories
  76. | Category | Tools | Examples |
  77. |----------|-------|---------|
  78. | **Scene Operations** | 23 | Create whole node trees in one call, add/remove/move nodes, set any property including textures, shapes, meshes and materials (by file path or inline), attach scripts, signals, groups, call methods |
  79. | **Project & Runtime** | 28 | Run/stop the game, send input, take screenshots, inspect live nodes, read errors and logs, project settings, input map, autoloads |
  80. | **Script & File Operations** | 8 | Edit and validate scripts, write files, rename/move files with reference updates, create and delete folders |
  81. | **File Browsing** | 4 | Browse directories, read files, search the project, create scripts |
  82. | **Undo & Batching** | 4 | Undo/redo any AI change, run many changes as one all-or-nothing batch |
  83. | **Asset Generation** | 1 | Generate 2D sprites from SVG |
  84. | **Visualization** | 1 | Interactive browser-based project map and scene explorer |
  85. ### Interactive Visualizer
  86. Run `map_project` and get a browser-based explorer at `localhost:6510`:
  87. - Force-directed graph of all scripts and their relationships
  88. - Click any script to see variables, functions, signals, and connections
  89. - Edit code directly in the visualizer — changes sync to Godot in real time
  90. - Scene view with node property editing
  91. - Find usages before refactoring
  92. <img width="1710" height="1107" alt="image" src="https://github.com/user-attachments/assets/a9faf163-8b8b-43da-93ec-c7a651e8ac60" />
  93. ### Limitations
  94. AI cannot create 100% of a game by itself — it struggles with complex UI layouts, compositing scenes, and some node property manipulation. It's still in active development, so feedback is very welcome!
  95. ---
  96. ## Architecture
  97. ```
  98. ┌─────────────┐ MCP (stdio) ┌──────────────┐ WebSocket ┌──────────────┐
  99. │ AI Client │◄────────────────►│ MCP Server │◄─────────────►│ Godot Editor │
  100. │ (Claude, │ │ (Node.js) │ port 6505 │ (Plugin) │
  101. │ Cursor) │ │ │ │ │
  102. └─────────────┘ │ Visualizer │ │ 69 tool │
  103. │ HTTP :6510 │ │ handlers │
  104. └──────┬───────┘ └──────────────┘
  105. │
  106. ┌──────▼───────┐
  107. │ Browser │
  108. │ Visualizer │
  109. └──────────────┘
  110. ```
  111. ---
  112. ## Current Limitations
  113. - **Local only** — runs on localhost, no remote connections
  114. - **One Godot editor at a time** — multiple AI clients can connect concurrently, but they all share a single Godot instance
  115. - **Ctrl+Z does not reach AI changes** — the plugin writes to disk rather than the editor's live tree, so Godot's native undo has nothing to revert. Use the `mcp_undo` tool instead (ask the agent to undo).
  116. - **AI is still limited in Godot knowledge** — it can't create 100% of the game alone, but it can help debug, write scripts, and tag along for the journey
  117. ---
  118. ## Development
  119. To build from source instead of using npm:
  120. ```bash
  121. cd mcp-server
  122. npm install
  123. npm run build
  124. ```
  125. Then point your AI client at `mcp-server/dist/index.js` instead of using `npx`.
  126. ---
  127. ## Release notes
  128. Narrative write-ups of each release live in [`release-notes/`](./release-notes/) (latest: [v0.6.1](./release-notes/v0.6.1.md)). For the full change history, see [`CHANGELOG.md`](./CHANGELOG.md).
  129. ---
  130. ## License
  131. MIT
  132. ---
  133. ## Star History
  134. <a href="https://www.star-history.com/?repos=tomyud1%2Fgodot-mcp&type=date&legend=top-left">
  135. <picture>
  136. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=tomyud1/godot-mcp&type=date&theme=dark&legend=top-left" />
  137. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=tomyud1/godot-mcp&type=date&legend=top-left" />
  138. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=tomyud1/godot-mcp&type=date&legend=top-left" />
  139. </picture>
  140. </a>
  141. ---
  142. **[Godot Asset Store](https://store.godotengine.org/asset/tomer-yud/godlink/)** · **[npm package](https://www.npmjs.com/package/godot-mcp-server)** · **[Report Issues](https://github.com/tomyud1/godot-mcp/issues)**

Ratings and comments

Sign in to rate this skill.

Sign in

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