Skip to content
Back to search

Godot-MCP-Native

一款支持godot开源引擎的的mcp插件,支持常见godot引擎操作,使用Godot原生实现MCPServer,无需安装依赖,开箱即用,支持多种AI工具调用。An MCP plugin that supports the open-source Godot engine, enabling common Godot engine operations. It implements the MCP Server using Godot's native HTTP, requires no dependency installation, is ready to use out of the box, and supports invocation by various AI tools.

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

HTML

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

Method 1: Asset Library (Recommended)

1. Open your Godot project 2. Go to **AssetLib** tab in the editor 3. Search for "Godot MCP Native" 4. Click **Download** and then **Install**

Method 2: Manual Installation

1. Download or clone this repository 2. Copy the `addons/godot_mcp` folder to your project's `addons/` directory 3. Open your project in Godot 4. Go to **Project > Project Settings > Plugins** 5. Enable "Godot MCP Native" plugin

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 · 434 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 Native (Model Context Protocol)
  2. [中文版本](https://github.com/yurineko73/Godot-MCP-Native/blob/main/README.zh.md)
  3. ![Godot Version](https://img.shields.io/badge/Godot-4.x-blue?logo=godot-engine)
  4. ![License](https://img.shields.io/badge/License-MIT-green)
  5. ![Version](https://img.shields.io/badge/Version-1.0.8-brightgreen)
  6. A powerful Godot Engine plugin that integrates AI assistants (Claude, etc.) via the Model Context Protocol (MCP). Enable AI to directly read and modify your Godot projects - scenes, scripts, nodes, and resources - all through natural language.
  7. ## 🚀 Features
  8. - **Full Project Access**: AI assistants can read and modify scripts, scenes, nodes, and resources
  9. - **Native Implementation**: No Node.js dependency required - runs entirely within Godot
  10. - **Real-time Editing**: Apply AI suggestions directly in the editor
  11. - **Comprehensive Tool Set** (155 tools — 30 core + 125 supplementary):
  12. - **Node Tools** (9 core + 11 advanced): Create, modify, manage scene nodes, duplicate, move, rename, signal connections, anchor presets, group management, batch operations, scene auditing
  13. - **Script Tools** (7 core + 8 advanced): Edit, analyze, create, attach, validate GDScript and C# files, execute scripts, search in files, symbol indexing, definition & reference lookup
  14. - **Scene Tools** (4 core + 4 advanced): Manipulate scene structure, save scenes, list/open/close scene tabs, project scene listing
  15. - **Editor Tools** (4 core + 12 advanced): Control editor functionality, screenshot, signal inspection, filesystem reload, node/file selection, export management, property inspector
  16. - **Debug Tools** (3 core + 68 advanced): Logging, debugger sessions, breakpoints, stack/variable inspection, profilers, runtime probe, animation/audio/shader/tilemap runtime control, debug execution control, await_scene_ready
  17. - **Project Tools** (3 core + 23 advanced): Access project settings, list resources, create resources, run tests, manage input mappings, inspect autoloads/global classes, resource diagnostics & health audit
  18. ## 🖥️ gdmcp CLI (Agent-First Interface)
  19. For coding agents (Codex, Claude Code, Cursor) that have shell access, the **gdmcp CLI**
  20. is the recommended way to interact with Godot MCP. Instead of loading all 155 tool
  21. schemas into model context, the CLI uses progressive discovery — ~33 domain commands
  22. for common operations, and on-demand schema retrieval for supplementary tools.
  23. ```bash
  24. # Quick start
  25. gdmcp --json doctor
  26. gdmcp --json scenes tree --depth 4
  27. gdmcp --json scripts read res://player.gd --lines 1:200
  28. gdmcp --json nodes properties set /root/Player --property speed --value 300
  29. ```
  30. **Installation**: Open the Godot editor → MCP dock → **CLI Tools** tab, or download
  31. from [GitHub Releases](https://github.com/yurineko73/Godot-MCP-Native/releases).
  32. See the [CLI README](https://github.com/yurineko73/Godot-MCP-Native/blob/main/cli/gdmcp/README.md) and [CLI Reference](https://github.com/yurineko73/Godot-MCP-Native/blob/main/docs/current/gdmcp-cli-reference.md)
  33. for full documentation.
  34. **Skill**: Install the companion Codex skill from [skills/gdmcp/](https://github.com/yurineko73/Godot-MCP-Native/blob/main/skills/gdmcp) to teach your
  35. agent the CLI workflow. Copy [skills/gdmcp/](https://github.com/yurineko73/Godot-MCP-Native/blob/main/skills/gdmcp) to `~/.codex/skills/gdmcp/`.
  36. ## 📦 Installation
  37. ### Method 1: Asset Library (Recommended)
  38. 1. Open your Godot project
  39. 2. Go to **AssetLib** tab in the editor
  40. 3. Search for "Godot MCP Native"
  41. 4. Click **Download** and then **Install**
  42. ### Method 2: Manual Installation
  43. 1. Download or clone this repository
  44. 2. Copy the `addons/godot_mcp` folder to your project's `addons/` directory
  45. 3. Open your project in Godot
  46. 4. Go to **Project > Project Settings > Plugins**
  47. 5. Enable "Godot MCP Native" plugin
  48. ## 🔧 Usage
  49. ### Enabling the Plugin
  50. 1. Open **Project > Project Settings > Plugins**
  51. 2. Locate "Godot MCP Native" in the list
  52. 3. Set the status to **Enable**
  53. ### Configuring MCP Server
  54. The plugin provides two transport modes:
  55. #### HTTP Mode (for remote access)
  56. - Best for: Network-based AI integration
  57. - Configuration: Set `transport_mode = "http"` and configure `http_port` (default: 9080)
  58. - Optional: Enable `auth_enabled` and set `auth_token` for security
  59. #### Headless / Command-line Launch
  60. Launch the editor in headless MCP-server mode:
  61. ```bash
  62. godot --editor --path /path/to/project -- --mcp-server
  63. ```
  64. Settings changed in the panel persist to `user://mcp_settings.cfg`. Headless
  65. `--mcp-server` mode **honors this file**, so the `http_port` / `transport_mode`
  66. / auth options configured via the editor UI are respected when running headlessly.
  67. To run **multiple instances in parallel** (several projects, or isolated test
  68. instances), override the port per launch with command-line flags — the command
  69. line takes precedence over the persisted config:
  70. ```bash
  71. godot --editor --path /path/to/projectA -- --mcp-server --mcp-port=9080
  72. godot --editor --path /path/to/projectB -- --mcp-server --mcp-port=19081
  73. ```
  74. | Flag | Value | Effect |
  75. | --- | --- | --- |
  76. | `--mcp-port=N` | `1024`–`65535` | Override `http_port` (out-of-range values ignored) |
  77. | `--mcp-transport=MODE` | `http` \| `stdio` | Override `transport_mode` (unknown values ignored) |
  78. ### Connecting with Claude Desktop
  79. First, install the `mcp-remote` package:
  80. ```bash
  81. npm install mcp-remote
  82. ```
  83. #### HTTP Mode Configuration
  84. ```json
  85. {
  86. "mcpServers": {
  87. "godot-mcp": {
  88. "command": "npx",
  89. "args": [
  90. "mcp-remote",
  91. "http://localhost:9080/mcp"
  92. ]
  93. }
  94. }
  95. }
  96. ```
  97. ### Connecting with Cursor / Trae
  98. #### HTTP Mode Configuration
  99. ```json
  100. {
  101. "mcpServers": {
  102. "godot-mcp": {
  103. "url": "http://localhost:9080/mcp"
  104. }
  105. }
  106. }
  107. ```
  108. With authentication:
  109. ```json
  110. {
  111. "mcpServers": {
  112. "godot-mcp": {
  113. "url": "http://localhost:9080/mcp",
  114. "headers": {
  115. "Authorization": "Bearer your-secret-token-here"
  116. }
  117. }
  118. }
  119. }
  120. ```
  121. ### Connecting with Cline
  122. #### HTTP Mode Configuration
  123. ```json
  124. {
  125. "mcpServers": {
  126. "godot-mcp": {
  127. "url": "http://localhost:9080/mcp",
  128. "type": "streamableHttp",
  129. "disabled": false,
  130. "autoApprove": []
  131. }
  132. }
  133. }
  134. ```
  135. ### Connecting with OpenCode
  136. #### HTTP Mode Configuration
  137. Remarks: If OpenCode is running in Windows Subsystem for Linux (WSL), you might need to configure the url to "http://<ip addresss of your host machine>:9080/mcp". WSL guide: https://learn.microsoft.com/en-us/windows/wsl/networking#accessing-windows-networking-apps-from-linux-host-ip
  138. ```json
  139. {
  140. "mcp": {
  141. "godot-mcp": {
  142. "type": "remote",
  143. "url": "http://localhost:9080/mcp"
  144. }
  145. }
  146. }
  147. ```
  148. ### Connecting with Codex
  149. #### HTTP Mode Configuration
  150. ```toml
  151. [mcp_servers]
  152. [mcp_servers.godot-mcp]
  153. type = "streamableHttp"
  154. url = "http://localhost:9080/mcp"
  155. ```
  156. ## 💬 Example Prompts
  157. Once connected, you can interact with your Godot project through Claude:
  158. ```
  159. @mcp godot-mcp read godot://script/current
  160. I need help optimizing my player movement code. Can you suggest improvements?
  161. ```
  162. ```
  163. @mcp godot-mcp get-scene-tree
  164. Add a cube in the middle of the scene and create a camera that looks at it.
  165. ```
  166. ```
  167. Create a main menu with Play, Options, and Quit buttons
  168. ```
  169. ```
  170. Implement a day/night cycle system with dynamic lighting
  171. ```
  172. ## 📚 Available Commands
  173. ### Node-Write (6)
  174. - `create-node` - Create a new node
  175. - `delete-node` - Delete a node
  176. - `update-node-property` - Update node properties
  177. - `duplicate-node` - Duplicate a node and its children
  178. - `move-node` - Move a node to a new parent
  179. - `rename-node` - Rename a node in the scene
  180. ### Node-Read (3)
  181. - `get-scene-tree` - Get scene tree structure
  182. - `get-node-properties` - Get properties of a specific node
  183. - `list-nodes` - List nodes under a parent
  184. ### Node-Write-Advanced (5)
  185. - `set-anchor-preset` - Set anchor preset for Control nodes
  186. - `connect-signal` - Connect a signal between nodes
  187. - `disconnect-signal` - Disconnect a signal connection
  188. - `set-node-groups` - Set group memberships for a node
  189. - `add-resource` - Add a resource child node (collision shape, mesh, etc.)
  190. ### Node-Advanced (6)
  191. - `get-node-groups` - Get groups a node belongs to
  192. - `find-nodes-in-group` - Find all nodes in a specific group
  193. - `batch-update-node-properties` - Batch update multiple node properties in one UndoRedo action
  194. - `batch-scene-node-edits` - Apply batch scene node create/delete/move edits in one UndoRedo action
  195. - `audit-scene-node-persistence` - Audit node owner and persistence state for the scene
  196. - `audit-scene-inheritance` - Audit inherited/instanced scene structure
  197. ### Script (7)
  198. - `list-project-scripts` - List all scripts
  199. - `read-script` - Read a specific script
  200. - `modify-script` - Update script content
  201. - `create-script` - Create a new script
  202. - `get-current-script` - Get currently editing script
  203. - `attach-script` - Attach an existing script to a node
  204. - `execute-script` - Execute GDScript expression
  205. ### Script-Advanced (8)
  206. - `analyze-script` - Analyze script structure
  207. - `validate-script` - Validate GDScript syntax
  208. - `search-in-files` - Search project files
  209. - `list-project-script-symbols` - Index script symbols across GDScript and C# files
  210. - `find-script-symbol-definition` - Find definition locations for a script symbol
  211. - `find-script-symbol-references` - Find textual references to a script symbol
  212. - `rename-script-symbol` - Rename a script symbol across project files
  213. - `open-script-at-line` - Open a script at a specific line in the editor
  214. ### Scene (4)
  215. - `create-scene` - Create a new scene
  216. - `save-scene` - Save current scene
  217. - `open-scene` - Open a scene
  218. - `get-current-scene` - Get current scene info
  219. ### Scene-Advanced (4)
  220. - `list-project-scenes` - List all scenes
  221. - `get-scene-structure` - Get scene structure details
  222. - `list-open-scenes` - List currently open scene tabs
  223. - `close-scene-tab` - Close a scene tab
  224. ### Editor (4)
  225. - `get-editor-state` - Get current editor state
  226. - `run-project` - Run the project
  227. - `stop-project` - Stop the running project
  228. - `execute-editor-script` - Execute GDScript script
  229. ### Editor-Advanced (12)
  230. - `get-selected-nodes` - Get selected nodes
  231. - `set-editor-setting` - Modify editor settings
  232. - `get-editor-screenshot` - Capture an editor viewport screenshot
  233. - `get-signals` - Inspect node signals and connections
  234. - `reload-project` - Rescan the project filesystem
  235. - `select-node` - Select a node in the scene and focus in Inspector
  236. - `select-file` - Select a file in the FileSystem dock
  237. - `get-inspector-properties` - Inspect node/resource properties like the Inspector
  238. - `list-export-presets` - List export presets
  239. - `inspect-export-templates` - Inspect installed export templates
  240. - `validate-export-preset` - Validate an export preset
  241. - `run-export` - Run a Godot CLI export
  242. ### Debug (3 core + 68 advanced)
  243. - `get-editor-logs` - Get editor/runtime logs
  244. - `debug-print` - Print debug info
  245. - `clear-output` - Clear MCP/editor output buffers
  246. - `get-performance-metrics` - Get performance data
  247. - `get-debugger-sessions` - List editor debugger sessions and active/break state
  248. - `set-debugger-breakpoint` - Enable or disable debugger breakpoints
  249. - `send-debugger-message` - Send custom messages to the running game debugger
  250. - `toggle-debugger-profiler` - Toggle EngineProfiler channels in active sessions
  251. - `get-debugger-messages` - Read custom runtime messages captured by the bridge
  252. - `add-debugger-capture-prefix` - Capture additional EngineDebugger message prefixes
  253. - `get-debug-stack-frames` - Read captured script stack frames from a breaked session
  254. - `get-debug-stack-variables` - Read locals, members, and globals for a captured stack frame
  255. - `install-runtime-probe` - Add the MCP runtime probe node to the current scene
  256. - `remove-runtime-probe` - Remove the MCP runtime probe node from the current scene
  257. - `request-debug-break` - Ask the runtime probe to enter Godot's debug break loop
  258. - `send-debug-command` - Send step/next/out/continue/stack debugger commands to breaked sessions
  259. - `get-runtime-info` - Query runtime metrics (FPS, node count, etc.) through the probe
  260. - `await-scene-ready` - Wait until a specific scene is loaded through the probe
  261. - `get-runtime-scene-tree` - Read the live runtime scene tree from the running game
  262. - `inspect-runtime-node` - Inspect a live runtime node and its serializable properties
  263. - `update-runtime-node-property` - Modify a property on a live runtime node
  264. - `call-runtime-node-method` - Call a method on a live runtime node
  265. - `evaluate-runtime-expression` - Evaluate a GDScript expression in the running game
  266. - `await-runtime-condition` - Poll a runtime expression until truthy or timeout
  267. - `assert-runtime-condition` - Assert a runtime expression becomes truthy within timeout
  268. - `get-debug-threads` - Return DAP-style debugger threads
  269. - `get-debug-state-events` - Read recorded debugger state transitions
  270. - `get-debug-output` - Read categorized runtime debugger output
  271. - `get-debug-scopes` - Group stack variables into DAP-like scopes
  272. - `get-debug-variables` - Resolve DAP-style variable references
  273. - `expand-debug-variable` - Expand a debug variable by scope and path
  274. - `evaluate-debug-expression` - Evaluate an expression in debugger context
  275. - `debug-step-into` / `debug-step-over` / `debug-step-out` / `debug-continue` - Debug execution control
  276. - `debug-step-into-and-wait` / `debug-step-over-and-wait` / `debug-step-out-and-wait` / `debug-continue-and-wait` - Debug execution with state wait
  277. - `await-debugger-state` - Check debugger session execution state
  278. - `get-runtime-performance-snapshot` - Capture runtime performance snapshot
  279. - `get-runtime-memory-trend` - Capture runtime memory trend
  280. - `create-runtime-node` - Create a node in the running game
  281. - `delete-runtime-node` - Delete a node from the running game
  282. - `simulate-runtime-input-event` - Inject structured InputEvent
  283. - `simulate-runtime-input-action` - Inject InputEventAction
  284. - `list-runtime-input-actions` - List runtime InputMap actions
  285. - `upsert-runtime-input-action` - Create/update a runtime InputMap action
  286. - `remove-runtime-input-action` - Remove a runtime InputMap action
  287. - `list-runtime-animations` - List animations on a runtime AnimationPlayer
  288. - `play-runtime-animation` - Play a runtime animation
  289. - `stop-runtime-animation` - Stop a runtime animation
  290. - `get-runtime-animation-state` - Get runtime animation playback state
  291. - `get-runtime-animation-tree-state` - Get runtime AnimationTree state
  292. - `set-runtime-animation-tree-active` - Enable/disable runtime AnimationTree
  293. - `travel-runtime-animation-tree` - Travel runtime animation state machine
  294. - `get-runtime-material-state` - Resolve runtime node material binding
  295. - `get-runtime-theme-item` - Resolve runtime Control theme item
  296. - `set-runtime-theme-override` - Apply runtime theme override
  297. - `clear-runtime-theme-override` - Remove runtime theme override
  298. - `get-runtime-shader-parameters` - List runtime shader parameters
  299. - `set-runtime-shader-parameter` - Update runtime shader uniform
  300. - `list-runtime-tilemap-layers` - List runtime TileMap layers
  301. - `get-runtime-tilemap-cell` - Get runtime TileMap cell data
  302. - `set-runtime-tilemap-cell` - Write/erase runtime TileMap cell
  303. - `list-runtime-audio-buses` - List runtime audio buses
  304. - `get-runtime-audio-bus` - Get runtime audio bus state
  305. - `update-runtime-audio-bus` - Update runtime audio bus
  306. - `get-runtime-screenshot` - Capture runtime viewport screenshot
  307. ### Project (3 core + 23 advanced)
  308. - `get-project-info` - Get project information
  309. - `get-project-settings` - Get project settings
  310. - `list-project-resources` - List project resources
  311. - `create-resource` - Create a new resource
  312. - `get-project-structure` - Get project directory structure
  313. - `list-project-tests` - Discover and list runnable project tests
  314. - `run-project-test` - Run a single project test
  315. - `run-project-tests` - Run multiple project tests
  316. - `list-project-input-actions` - List project InputMap actions
  317. - `upsert-project-input-action` - Create or update a project InputMap action
  318. - `remove-project-input-action` - Remove a project InputMap action
  319. - `list-project-autoloads` - List project autoload entries
  320. - `list-project-global-classes` - List project global script classes
  321. - `get-class-api-metadata` - Get ClassDB or global class API metadata
  322. - `inspect-csharp-project-support` - Inspect C# project support files
  323. - `compare-render-screenshots` - Compare two screenshots for pixel differences
  324. - `inspect-tileset-resource` - Inspect a TileSet resource
  325. - `reimport-resources` - Reimport resources through the import pipeline
  326. - `get-import-metadata` - Get resource import metadata
  327. - `get-resource-uid-info` - Inspect ResourceUID mappings
  328. - `fix-resource-uid` - Ensure a resource has a persisted UID
  329. - `get-resource-dependencies` - List resource dependencies
  330. - `scan-missing-resource-dependencies` - Find broken dependency references
  331. - `scan-cyclic-resource-dependencies` - Find cyclic dependency chains
  332. - `detect-broken-scripts` - Scan scripts for syntax errors
  333. - `audit-project-health` - Run a project health audit
  334. ## 🔒 Security Recommendations
  335. - ✅ **Production**: Always enable authentication (`auth_enabled = true`)
  336. - ✅ **Token**: Use a strong token (≥16 characters with letters, numbers, special characters)
  337. - ✅ **Storage**: Don't commit tokens to version control
  338. - ⚠️ **Remote Access**: Use HTTPS (TLS/SSL) for network access
  339. ## 📋 Requirements
  340. - Godot Engine 4.x (recommended 4.5 or higher)
  341. - No additional dependencies (native implementation)
  342. ## 📖 Documentation
  343. For detailed documentation, see the `docs/current/` folder:
  344. - [Quick Start Guide](https://github.com/yurineko73/Godot-MCP-Native/blob/main/docs/current/quickstart.md)
  345. - [Architecture Design](https://github.com/yurineko73/Godot-MCP-Native/blob/main/docs/current/architecture.md)
  346. - [Tools Reference](https://github.com/yurineko73/Godot-MCP-Native/blob/main/docs/current/tools-reference.md)
  347. - [CLI Reference](https://github.com/yurineko73/Godot-MCP-Native/blob/main/docs/current/gdmcp-cli-reference.md)
  348. - [Release Workflow](https://github.com/yurineko73/Godot-MCP-Native/blob/main/docs/development/release-workflow.md)
  349. - [Testing Guide](https://github.com/yurineko73/Godot-MCP-Native/blob/main/docs/current/testing-guide.md)
  350. ## 🤝 Contributing
  351. Contributions are welcome! Please feel free to submit a Pull Request.
  352. ## 📄 License
  353. This project is licensed under the MIT License - see the [LICENSE](https://github.com/yurineko73/Godot-MCP-Native/blob/main/LICENSE) file for details.
  354. ## 👤 Author
  355. **yurineko73**
  356. ## 🙏 Acknowledgments
  357. - Godot Engine team for the amazing game engine
  358. - Model Context Protocol (MCP) specification
  359. - Claude AI by Anthropic for inspiring this integration
  360. ---
  361. **Note**: This is a community plugin and is not officially affiliated with Godot Engine or Anthropic.

Ratings and comments

Sign in to rate this skill.

Sign in

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