Skip to content
Back to search

godot-mcp

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.

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

HTML

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

git clone https://github.com/tugcantopaloglu/godot-mcp.git
cd godot-mcp
npm install
npm run build

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 · 684 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. <img width="2752" height="1536" alt="godot_mcp_header" src="https://github.com/user-attachments/assets/ed7ac605-8fb5-4a5f-adf8-4b6912cbc18c" />
  2. # Godot MCP - Full Control
  3. [![](https://badge.mcpx.dev?type=server 'MCP Server')](https://modelcontextprotocol.io/introduction)
  4. [![Made with Godot](https://img.shields.io/badge/Made%20with-Godot-478CBF?style=flat&logo=godot%20engine&logoColor=white)](https://godotengine.org)
  5. [![](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white 'TypeScript')](https://www.typescriptlang.org/)
  6. [![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)
  7. A comprehensive [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server that gives AI assistants **full control** over the Godot game engine. **157 tools** spanning networking, 3D/2D rendering, UI controls, audio effects, animation trees, file I/O, runtime code execution, property inspection, scene manipulation, signal management, physics, project creation, and more.
  8. ## Acknowledgments
  9. This project is built upon and extends [godot-mcp](https://github.com/Coding-Solo/godot-mcp) by [Solomon Elias (Coding-Solo)](https://github.com/Coding-Solo). The original project provided the foundational architecture including the TypeScript MCP server, headless GDScript operations system, and TCP-based runtime interaction server. Thank you for making this possible with your excellent open-source work!
  10. ## What's New (Improvements Over Original)
  11. The original godot-mcp provided 20 tools for basic project management and scene creation. This fork extends it to **157 tools** with the following major additions:
  12. ### New in 3.1
  13. - **`validate_script` autoload resolution** - Script validation now compiles the target through a `SceneTree` at `_initialize()` (after project autoloads are registered) instead of `--check-only` at `_init()`. References to autoload singletons no longer produce false `Identifier not found` errors, while real syntax/type errors are still caught. Verified building a full game whose scripts reference several autoloads.
  14. - **`manage_input_map` event merging** - Adding a second key to an existing input action now merges it into that action's `events` array (with `physical_keycode` de-duplication) instead of writing a duplicate `actionname=` line, which previously left `project.godot` malformed and silently dropped earlier bindings.
  15. ### New in 3.0
  16. - **.NET / C# support** - Scaffold C# projects and generate C# scripts (`create_project` with `dotnet: true`, `create_csharp_script`); the `.csproj` SDK version is matched to your installed Godot.
  17. - **GDScript diagnostics** - Validate scripts for syntax and type errors without running the game (`validate_script`, and `validate_scripts` for all git-changed or project-wide files).
  18. - **Correctness and robustness fixes** across the headless scene operations and the runtime interaction server (resource-typed properties now persist, reparenting works, runtime commands are correlated by request id, and the tools survive projects with warnings-as-errors). Requires Godot 4.4 or later; tested and working with the latest Godot **4.7**.
  19. ### Runtime Code Execution
  20. - **`game_eval`** - Execute arbitrary GDScript code in the running game with return values
  21. - Full `await` support for async GDScript code
  22. - Works even when the game is paused (`PROCESS_MODE_ALWAYS`)
  23. ### Runtime Node Inspection & Manipulation
  24. - **`game_get_property`** / **`game_set_property`** - Read/write any property on any node by path
  25. - **`game_call_method`** - Call any method on any node with arguments
  26. - **`game_get_node_info`** - Full node introspection: properties, signals, methods, children
  27. - **`game_instantiate_scene`** - Dynamically add scenes to the running game
  28. - **`game_remove_node`** - Remove nodes at runtime
  29. - **`game_change_scene`** - Switch scenes at runtime
  30. - **`game_reparent_node`** - Move nodes between parents
  31. ### Signal System
  32. - **`game_connect_signal`** - Wire up signal connections at runtime
  33. - **`game_disconnect_signal`** - Remove signal connections
  34. - **`game_emit_signal`** - Emit signals with arguments
  35. ### Animation & Tweening
  36. - **`game_play_animation`** - Control AnimationPlayer (play, stop, pause, list)
  37. - **`game_tween_property`** - Smooth property animation with configurable easing
  38. ### Game Control & Debugging
  39. - **`game_pause`** - Pause/unpause the game
  40. - **`game_performance`** - FPS, frame time, memory, object counts, draw calls
  41. - **`game_wait`** - Wait N frames (timing-sensitive operations)
  42. - **`game_get_nodes_in_group`** - Query nodes by group
  43. - **`game_find_nodes_by_class`** - Find all nodes of a specific class
  44. ### Headless Scene Operations (No Running Game Needed)
  45. - **`read_scene`** - Parse any .tscn file and get full node tree with properties as JSON
  46. - **`modify_scene_node`** - Change node properties in scene files
  47. - **`remove_scene_node`** - Remove nodes from scene files
  48. - **`attach_script`** - Attach GDScript files to nodes in scenes
  49. - **`create_resource`** - Create .tres resource files (materials, themes, etc.)
  50. ### Project Management
  51. - **`read_project_settings`** - Parse project.godot as structured JSON
  52. - **`modify_project_settings`** - Change project settings programmatically
  53. - **`list_project_files`** - List and filter project files by extension
  54. ### File I/O
  55. - **`read_file`** / **`write_file`** / **`delete_file`** - Full file system access within Godot projects
  56. - **`create_directory`** - Create directory structures for scripts, scenes, assets
  57. ### Error & Log Capture
  58. - **`game_get_errors`** - Get new push_error/push_warning messages since last call
  59. - **`game_get_logs`** - Get new print output from the running game since last call
  60. ### Enhanced Input
  61. - **`game_key_hold`** / **`game_key_release`** - Hold keys down for movement testing (WASD etc.)
  62. - **`game_scroll`** - Mouse scroll wheel events
  63. - **`game_mouse_drag`** - Drag between two points over multiple frames
  64. - **`game_gamepad`** - Gamepad button and axis input events
  65. ### Project Creation & Configuration
  66. - **`create_project`** - Create a new Godot project from scratch (pass `dotnet: true` to scaffold a .NET/C# project)
  67. - **`create_csharp_script`** - Create a C# script in a Godot .NET project
  68. - **`manage_autoloads`** - Add, remove, or list autoloads
  69. - **`manage_input_map`** - Add, remove, or list input actions and key bindings
  70. - **`manage_export_presets`** - Create or modify export preset configuration
  71. ### .NET / C# Support
  72. - **`create_project`** with `dotnet: true` - Scaffold a Godot .NET project (`.csproj` with `Godot.NET.Sdk` matched to your Godot version, plus the `"C#"` feature flag)
  73. - **`create_csharp_script`** - Generate an idiomatic C# script (partial class, correct `_Ready`/`_Process` override signatures); the class name is kept in sync with the file name so Godot can attach it
  74. - **`get_project_info`** reports an `isDotnet` field
  75. ### GDScript Diagnostics
  76. - **`validate_script`** - Check a single GDScript file for syntax and type errors headlessly, returning `{ valid, errors: [{ message, file, line }] }`
  77. - **`validate_scripts`** - Batch-validate all git-changed `.gd` files (or the whole project), so an agent can verify its edits before running the game
  78. ### Camera, Physics & Audio
  79. - **`game_get_camera`** / **`game_set_camera`** - Query and control 2D/3D cameras
  80. - **`game_raycast`** - Cast physics rays (auto-detects 2D vs 3D)
  81. - **`game_get_audio`** - Get audio bus layout and playing streams
  82. - **`game_spawn_node`** - Create any node type at runtime with properties
  83. - **`game_set_shader_param`** - Set shader parameters on materials
  84. - **`game_audio_play`** / **`game_audio_bus`** - Full audio playback and bus control
  85. - **`game_navigate_path`** - Query navigation paths (2D/3D)
  86. - **`game_tilemap`** - Get/set TileMapLayer cells
  87. - **`game_add_collision`** - Add collision shapes to physics bodies
  88. - **`game_environment`** - Configure post-processing (fog, glow, SSAO, tonemap, etc.)
  89. - **`game_manage_group`** - Add/remove nodes from groups
  90. - **`game_create_timer`** - Create timer nodes programmatically
  91. - **`game_set_particles`** - Configure GPUParticles2D/3D properties and process materials
  92. - **`game_create_animation`** - Create animations with value/method/bezier/audio tracks and keyframes
  93. - **`export_project`** - Trigger headless project export builds (CI/CD ready)
  94. - **`game_serialize_state`** - Save/load entire node tree state as JSON
  95. - **`game_physics_body`** - Configure mass, velocity, damping, friction, bounce
  96. - **`game_create_joint`** - Create physics joints (pin, spring, hinge, cone, slider)
  97. - **`game_bone_pose`** - Get/set skeleton bone poses for character animation
  98. - **`game_ui_theme`** - Apply color, constant, and font size theme overrides
  99. - **`game_viewport`** - Create/configure SubViewport nodes
  100. - **`game_debug_draw`** - Draw debug geometry (lines, spheres, boxes)
  101. ### Networking
  102. - **`game_http_request`** - HTTP GET/POST/PUT/DELETE with headers and body
  103. - **`game_websocket`** - WebSocket client connect/disconnect/send messages
  104. - **`game_multiplayer`** - ENet multiplayer create server/client/disconnect
  105. - **`game_rpc`** - Call or configure RPC methods on nodes
  106. ### System & Window Control
  107. - **`game_script`** - Attach, detach, or get source of node scripts at runtime
  108. - **`game_window`** - Get/set window size, fullscreen, title, position
  109. - **`game_os_info`** - Get platform, locale, screen, adapter, memory info
  110. - **`game_time_scale`** - Get/set Engine.time_scale and timing info
  111. - **`game_process_mode`** - Set node process mode (pausable/always/disabled)
  112. - **`game_world_settings`** - Get/set gravity, physics FPS, and world settings
  113. ### Advanced Signals & Input
  114. - **`game_list_signals`** - List all signals on a node with connections
  115. - **`game_await_signal`** - Await a signal with timeout and return args
  116. - **`game_touch`** - Simulate touch press/release/drag and gestures
  117. - **`game_input_state`** - Query pressed keys, mouse position, connected pads
  118. - **`game_input_action`** - Manage runtime InputMap actions and strength
  119. ### 3D Rendering & Geometry
  120. - **`game_csg`** - Create/configure CSG nodes with boolean operations
  121. - **`game_multimesh`** - Create/configure MultiMeshInstance3D for instancing
  122. - **`game_procedural_mesh`** - Generate meshes via ArrayMesh from vertex data
  123. - **`game_light_3d`** - Create/configure 3D lights (directional/omni/spot)
  124. - **`game_mesh_instance`** - Create MeshInstance3D with primitive meshes
  125. - **`game_gridmap`** - GridMap set/get/clear cells and query used cells
  126. - **`game_3d_effects`** - Create ReflectionProbe, Decal, or FogVolume
  127. - **`game_gi`** - Create/configure VoxelGI or LightmapGI
  128. - **`game_path_3d`** - Create Path3D/Curve3D and manage curve points
  129. - **`game_sky`** - Create/configure Sky with procedural/physical sky
  130. - **`game_camera_attributes`** - Configure DOF, exposure, auto-exposure on camera
  131. - **`game_navigation_3d`** - Create/configure NavigationRegion3D and bake
  132. - **`game_physics_3d`** - Area3D queries and point/shape intersection tests
  133. ### 2D Systems
  134. - **`game_canvas`** - Create/configure CanvasLayer and CanvasModulate
  135. - **`game_canvas_draw`** - 2D drawing: line/rect/circle/polygon/text/clear
  136. - **`game_light_2d`** - Create/configure 2D lights and light occluders
  137. - **`game_parallax`** - Create/configure ParallaxBackground and layers
  138. - **`game_shape_2d`** - Line2D/Polygon2D point manipulation
  139. - **`game_path_2d`** - Path2D/Curve2D management and AnimatedSprite2D
  140. - **`game_physics_2d`** - Area2D queries and 2D point/shape intersections
  141. ### Advanced Animation
  142. - **`game_animation_tree`** - AnimationTree state machine travel and params
  143. - **`game_animation_control`** - AnimationPlayer seek/queue/speed/info control
  144. - **`game_skeleton_ik`** - SkeletonIK3D start/stop/set target position
  145. ### Advanced Audio
  146. - **`game_audio_effect`** - Add/remove/configure audio bus effects
  147. - **`game_audio_bus_layout`** - Create/remove/reorder audio buses and routing
  148. - **`game_audio_spatial`** - Configure AudioStreamPlayer3D spatial properties
  149. ### Editor & Project Tools
  150. - **`rename_file`** - Rename or move a file within the project
  151. - **`manage_resource`** - Read or modify .tres/.res resource files
  152. - **`create_script`** - Create a GDScript file from a template
  153. - **`validate_script`** - Check a GDScript file for syntax/type errors headlessly (no run needed)
  154. - **`validate_scripts`** - Batch-check GDScript files: git-changed ones by default, or all
  155. - **`manage_scene_signals`** - List/add/remove signal connections in .tscn files
  156. - **`manage_layers`** - List/set named layer definitions in project
  157. - **`manage_plugins`** - List/enable/disable editor plugins
  158. - **`manage_shader`** - Create or read .gdshader files
  159. - **`manage_theme_resource`** - Create/read/modify Theme .tres resources
  160. - **`set_main_scene`** - Set the main scene in project.godot
  161. - **`manage_scene_structure`** - Rename/duplicate/move nodes within .tscn scenes
  162. - **`manage_translations`** - List/add/remove translation files in project
  163. - **`game_locale`** - Set/get locale and translate strings at runtime
  164. ### UI Controls
  165. - **`game_ui_control`** - Set focus, anchors, tooltip, mouse filter on Control
  166. - **`game_ui_text`** - LineEdit/TextEdit/RichTextLabel text operations
  167. - **`game_ui_popup`** - Show/hide/popup for Popup/Dialog/Window nodes
  168. - **`game_ui_tree`** - Tree control: get/select/collapse/add/remove items
  169. - **`game_ui_item_list`** - ItemList/OptionButton: get/select/add/remove items
  170. - **`game_ui_tabs`** - TabContainer/TabBar: get/set current tab
  171. - **`game_ui_menu`** - PopupMenu/MenuBar: add/remove/get menu items
  172. - **`game_ui_range`** - ProgressBar/Slider/SpinBox/ColorPicker get/set
  173. ### Rendering & Resources
  174. - **`game_render_settings`** - Get/set MSAA, FXAA, TAA, scaling mode/scale
  175. - **`game_resource`** - Runtime resource load, save, or preload
  176. ### Robustness Improvements
  177. - **Reentrancy guard** - Prevents concurrent command processing during async operations
  178. - **Full type conversion** - Supports Vector2/3, Color, Quaternion, Basis, Transform2D/3D, AABB, Rect2, and all packed array types
  179. - **Smart property type detection** - Uses node's `get_property_list()` for automatic type conversion
  180. - **PackedArray serialization** - Proper JSON arrays instead of string fallback
  181. - **Graceful error handling** - Scene read fallback to raw .tscn text on missing dependencies
  182. ## All 157 Tools
  183. ### Project Management (7 tools)
  184. | Tool | Description |
  185. |------|-------------|
  186. | `launch_editor` | Launch Godot editor for a project |
  187. | `run_project` | Run a Godot project and capture output |
  188. | `stop_project` | Stop the running project |
  189. | `get_debug_output` | Get console output and errors |
  190. | `get_godot_version` | Get installed Godot version |
  191. | `list_projects` | Find Godot projects in a directory |
  192. | `get_project_info` | Get project metadata |
  193. ### Scene Management (7 tools)
  194. | Tool | Description |
  195. |------|-------------|
  196. | `create_scene` | Create a new scene with a root node type |
  197. | `add_node` | Add a node to an existing scene |
  198. | `load_sprite` | Load a texture into a Sprite2D node |
  199. | `export_mesh_library` | Export a scene as MeshLibrary |
  200. | `save_scene` | Save a scene (with optional variant path) |
  201. | `get_uid` | Get UID for a file (Godot 4.4+) |
  202. | `update_project_uids` | Resave resources to update UIDs |
  203. ### Headless Scene Operations (5 tools)
  204. | Tool | Description |
  205. |------|-------------|
  206. | `read_scene` | Read full scene tree as JSON |
  207. | `modify_scene_node` | Modify node properties in a scene file |
  208. | `remove_scene_node` | Remove a node from a scene file |
  209. | `attach_script` | Attach a GDScript to a scene node |
  210. | `create_resource` | Create a .tres resource file |
  211. ### Project Settings (3 tools)
  212. | Tool | Description |
  213. |------|-------------|
  214. | `read_project_settings` | Parse project.godot as JSON |
  215. | `modify_project_settings` | Change a project setting |
  216. | `list_project_files` | List/filter project files |
  217. ### Runtime Input (4 tools)
  218. | Tool | Description |
  219. |------|-------------|
  220. | `game_screenshot` | Capture a screenshot (base64 PNG) |
  221. | `game_click` | Click at a position |
  222. | `game_key_press` | Send key press or input action |
  223. | `game_mouse_move` | Move the mouse |
  224. ### Runtime Inspection (3 tools)
  225. | Tool | Description |
  226. |------|-------------|
  227. | `game_get_ui` | Get all visible UI elements |
  228. | `game_get_scene_tree` | Get full scene tree structure |
  229. | `game_get_node_info` | Detailed node introspection |
  230. ### Runtime Code Execution (1 tool)
  231. | Tool | Description |
  232. |------|-------------|
  233. | `game_eval` | Execute arbitrary GDScript with return values |
  234. ### Runtime Node Manipulation (7 tools)
  235. | Tool | Description |
  236. |------|-------------|
  237. | `game_get_property` | Get any node property |
  238. | `game_set_property` | Set any node property (auto type conversion) |
  239. | `game_call_method` | Call any method on a node |
  240. | `game_instantiate_scene` | Add a PackedScene to the running tree |
  241. | `game_remove_node` | Remove a node from the tree |
  242. | `game_change_scene` | Switch to a different scene |
  243. | `game_reparent_node` | Move a node to a new parent |
  244. ### Runtime Signals (5 tools)
  245. | Tool | Description |
  246. |------|-------------|
  247. | `game_connect_signal` | Connect a signal to a method |
  248. | `game_disconnect_signal` | Disconnect a signal |
  249. | `game_emit_signal` | Emit a signal with arguments |
  250. | `game_list_signals` | List all signals on a node with connections |
  251. | `game_await_signal` | Await a signal with timeout and return args |
  252. ### Runtime Animation (2 tools)
  253. | Tool | Description |
  254. |------|-------------|
  255. | `game_play_animation` | Control AnimationPlayer |
  256. | `game_tween_property` | Tween a property with easing |
  257. ### Runtime Utilities (5 tools)
  258. | Tool | Description |
  259. |------|-------------|
  260. | `game_pause` | Pause/unpause the game |
  261. | `game_performance` | Get FPS, memory, draw calls |
  262. | `game_wait` | Wait N frames |
  263. | `game_get_nodes_in_group` | Query nodes by group |
  264. | `game_find_nodes_by_class` | Find nodes by class type |
  265. ### File I/O (4 tools)
  266. | Tool | Description |
  267. |------|-------------|
  268. | `read_file` | Read a text file from a Godot project |
  269. | `write_file` | Create or overwrite a text file |
  270. | `delete_file` | Delete a file from a project |
  271. | `create_directory` | Create a directory inside a project |
  272. ### Error & Log Capture (2 tools)
  273. | Tool | Description |
  274. |------|-------------|
  275. | `game_get_errors` | Get new errors/warnings since last call |
  276. | `game_get_logs` | Get new print output since last call |
  277. ### Enhanced Input (8 tools)
  278. | Tool | Description |
  279. |------|-------------|
  280. | `game_key_hold` | Hold a key down (no auto-release) |
  281. | `game_key_release` | Release a held key |
  282. | `game_scroll` | Mouse scroll wheel event |
  283. | `game_mouse_drag` | Drag between two points over N frames |
  284. | `game_gamepad` | Gamepad button or axis input |
  285. | `game_touch` | Simulate touch press/release/drag and gestures |
  286. | `game_input_state` | Query pressed keys, mouse position, connected pads |
  287. | `game_input_action` | Manage runtime InputMap actions and strength |
  288. ### Project Creation (5 tools)
  289. | Tool | Description |
  290. |------|-------------|
  291. | `create_project` | Create a new Godot project (supports `dotnet: true` for C#) |
  292. | `create_csharp_script` | Create a C# script in a Godot .NET project |
  293. | `manage_autoloads` | Add, remove, or list autoloads |
  294. | `manage_input_map` | Add, remove, or list input actions |
  295. | `manage_export_presets` | Create or modify export presets |
  296. ### Advanced Runtime (24 tools)
  297. | Tool | Description |
  298. |------|-------------|
  299. | `game_get_camera` | Get active camera position/rotation/zoom |
  300. | `game_set_camera` | Move or rotate the active camera |
  301. | `game_raycast` | Cast a ray and return collision results |
  302. | `game_get_audio` | Get audio bus layout and playing streams |
  303. | `game_spawn_node` | Create a new node of any type at runtime |
  304. | `game_set_shader_param` | Set a shader parameter on a node's material |
  305. | `game_audio_play` | Play, stop, or pause an AudioStreamPlayer node |
  306. | `game_audio_bus` | Set volume, mute, or solo on an audio bus |
  307. | `game_navigate_path` | Query a navigation path between two points |
  308. | `game_tilemap` | Get or set cells in a TileMapLayer node |
  309. | `game_add_collision` | Add a collision shape to a physics body node |
  310. | `game_environment` | Get or set environment and post-processing settings |
  311. | `game_manage_group` | Add or remove a node from a group, or list groups |
  312. | `game_create_timer` | Create a Timer node with configuration |
  313. | `game_set_particles` | Configure GPUParticles2D/3D node properties |
  314. | `game_create_animation` | Create an animation with tracks and keyframes |
  315. | `game_serialize_state` | Save or load node tree state as JSON |
  316. | `game_physics_body` | Configure physics body properties (mass, velocity) |
  317. | `game_create_joint` | Create a physics joint between two bodies |
  318. | `game_bone_pose` | Get or set bone poses on a Skeleton3D node |
  319. | `game_ui_theme` | Apply theme overrides to a Control node |
  320. | `game_viewport` | Create or configure a SubViewport node |
  321. | `game_debug_draw` | Draw debug lines, spheres, or boxes in 3D |
  322. ### Build & Export (1 tool)
  323. | Tool | Description |
  324. |------|-------------|
  325. | `export_project` | Export a Godot project using a preset |
  326. ### Networking (4 tools)
  327. | Tool | Description |
  328. |------|-------------|
  329. | `game_http_request` | HTTP GET/POST/PUT/DELETE with headers and body |
  330. | `game_websocket` | WebSocket client connect/disconnect/send messages |
  331. | `game_multiplayer` | ENet multiplayer create server/client/disconnect |
  332. | `game_rpc` | Call or configure RPC methods on nodes |
  333. ### System & Window (6 tools)
  334. | Tool | Description |
  335. |------|-------------|
  336. | `game_script` | Attach, detach, or get source of node scripts |
  337. | `game_window` | Get/set window size, fullscreen, title, position |
  338. | `game_os_info` | Get platform, locale, screen, adapter, memory info |
  339. | `game_time_scale` | Get/set Engine.time_scale and timing info |
  340. | `game_process_mode` | Set node process mode (pausable/always/disabled) |
  341. | `game_world_settings` | Get/set gravity, physics FPS, and world settings |
  342. ### 3D Rendering & Geometry (13 tools)
  343. | Tool | Description |
  344. |------|-------------|
  345. | `game_csg` | Create/configure CSG nodes with boolean operations |
  346. | `game_multimesh` | Create/configure MultiMeshInstance3D for instancing |
  347. | `game_procedural_mesh` | Generate meshes via ArrayMesh from vertex data |
  348. | `game_light_3d` | Create/configure 3D lights (directional/omni/spot) |
  349. | `game_mesh_instance` | Create MeshInstance3D with primitive meshes |
  350. | `game_gridmap` | GridMap set/get/clear cells and query used cells |
  351. | `game_3d_effects` | Create ReflectionProbe, Decal, or FogVolume |
  352. | `game_gi` | Create/configure VoxelGI or LightmapGI |
  353. | `game_path_3d` | Create Path3D/Curve3D and manage curve points |
  354. | `game_sky` | Create/configure Sky with procedural/physical sky |
  355. | `game_camera_attributes` | Configure DOF, exposure, auto-exposure on camera |
  356. | `game_navigation_3d` | Create/configure NavigationRegion3D and bake |
  357. | `game_physics_3d` | Area3D queries and point/shape intersection tests |
  358. ### 2D Systems (7 tools)
  359. | Tool | Description |
  360. |------|-------------|
  361. | `game_canvas` | Create/configure CanvasLayer and CanvasModulate |
  362. | `game_canvas_draw` | 2D drawing: line/rect/circle/polygon/text/clear |
  363. | `game_light_2d` | Create/configure 2D lights and light occluders |
  364. | `game_parallax` | Create/configure ParallaxBackground and layers |
  365. | `game_shape_2d` | Line2D/Polygon2D point manipulation |
  366. | `game_path_2d` | Path2D/Curve2D management and AnimatedSprite2D |
  367. | `game_physics_2d` | Area2D queries and 2D point/shape intersections |
  368. ### Advanced Animation (3 tools)
  369. | Tool | Description |
  370. |------|-------------|
  371. | `game_animation_tree` | AnimationTree state machine travel and params |
  372. | `game_animation_control` | AnimationPlayer seek/queue/speed/info control |
  373. | `game_skeleton_ik` | SkeletonIK3D start/stop/set target position |
  374. ### Advanced Audio (3 tools)
  375. | Tool | Description |
  376. |------|-------------|
  377. | `game_audio_effect` | Add/remove/configure audio bus effects |
  378. | `game_audio_bus_layout` | Create/remove/reorder audio buses and routing |
  379. | `game_audio_spatial` | Configure AudioStreamPlayer3D spatial properties |
  380. ### Editor & Project Tools (14 tools)
  381. | Tool | Description |
  382. |------|-------------|
  383. | `rename_file` | Rename or move a file within the project |
  384. | `manage_resource` | Read or modify .tres/.res resource files |
  385. | `create_script` | Create a GDScript file from a template |
  386. | `validate_script` | Check a GDScript file for syntax/type errors (headless) |
  387. | `validate_scripts` | Batch-check GDScript files (git-changed by default, or all) |
  388. | `manage_scene_signals` | List/add/remove signal connections in .tscn files |
  389. | `manage_layers` | List/set named layer definitions in project |
  390. | `manage_plugins` | List/enable/disable editor plugins |
  391. | `manage_shader` | Create or read .gdshader files |
  392. | `manage_theme_resource` | Create/read/modify Theme .tres resources |
  393. | `set_main_scene` | Set the main scene in project.godot |
  394. | `manage_scene_structure` | Rename/duplicate/move nodes within .tscn scenes |
  395. | `manage_translations` | List/add/remove translation files in project |
  396. | `game_locale` | Set/get locale and translate strings at runtime |
  397. ### UI Controls (8 tools)
  398. | Tool | Description |
  399. |------|-------------|
  400. | `game_ui_control` | Set focus, anchors, tooltip, mouse filter on Control |
  401. | `game_ui_text` | LineEdit/TextEdit/RichTextLabel text operations |
  402. | `game_ui_popup` | Show/hide/popup for Popup/Dialog/Window nodes |
  403. | `game_ui_tree` | Tree control: get/select/collapse/add/remove items |
  404. | `game_ui_item_list` | ItemList/OptionButton: get/select/add/remove items |
  405. | `game_ui_tabs` | TabContainer/TabBar: get/set current tab |
  406. | `game_ui_menu` | PopupMenu/MenuBar: add/remove/get menu items |
  407. | `game_ui_range` | ProgressBar/Slider/SpinBox/ColorPicker get/set |
  408. ### Rendering & Resources (2 tools)
  409. | Tool | Description |
  410. |------|-------------|
  411. | `game_render_settings` | Get/set MSAA, FXAA, TAA, scaling mode/scale |
  412. | `game_resource` | Runtime resource load, save, or preload |
  413. ## Requirements
  414. - [Godot Engine](https://godotengine.org/download) 4.4 or later (the headless operations script and UID features require 4.4+); tested and working with the latest Godot **4.7**
  415. - (Optional) [.NET SDK](https://dotnet.microsoft.com/download) 8.0+ and the Godot .NET (C#) build, only if you use `create_project`'s `dotnet: true` flag or `create_csharp_script`
  416. - [Node.js](https://nodejs.org/) >= 18.0.0
  417. - An AI assistant that supports MCP (Claude Code, Cline, Cursor, etc.)
  418. ## Installation
  419. ```bash
  420. git clone https://github.com/tugcantopaloglu/godot-mcp.git
  421. cd godot-mcp
  422. npm install
  423. npm run build
  424. ```
  425. ## Configuration
  426. ### Claude Code
  427. Add to your Claude Code MCP settings:
  428. ```json
  429. {
  430. "mcpServers": {
  431. "godot": {
  432. "command": "node",
  433. "args": ["/absolute/path/to/godot-mcp/build/index.js"],
  434. "env": {
  435. "GODOT_PATH": "/path/to/godot",
  436. "DEBUG": "true"
  437. }
  438. }
  439. }
  440. }
  441. ```
  442. ### Cline (VS Code)
  443. Add to your Cline MCP settings (`cline_mcp_settings.json`):
  444. ```json
  445. {
  446. "mcpServers": {
  447. "godot": {
  448. "command": "node",
  449. "args": ["/absolute/path/to/godot-mcp/build/index.js"],
  450. "disabled": false
  451. }
  452. }
  453. }
  454. ```
  455. ### Cursor
  456. Create `.cursor/mcp.json` in your project:
  457. ```json
  458. {
  459. "mcpServers": {
  460. "godot": {
  461. "command": "node",
  462. "args": ["/absolute/path/to/godot-mcp/build/index.js"]
  463. }
  464. }
  465. }
  466. ```
  467. ## Runtime Tools Setup
  468. To use the `game_*` runtime tools, your Godot project needs the MCP interaction server autoload. Copy `build/scripts/mcp_interaction_server.gd` to your project and register it as an autoload:
  469. 1. Copy `build/scripts/mcp_interaction_server.gd` to your project's scripts folder
  470. 2. In Godot: **Project > Project Settings > Autoload**
  471. 3. Add the script with the name `McpInteractionServer`
  472. The server listens on `127.0.0.1:9090` and accepts JSON commands over TCP when the game is running.
  473. ## Environment Variables
  474. | Variable | Description |
  475. |----------|-------------|
  476. | `GODOT_PATH` | Path to the Godot executable (overrides auto-detection) |
  477. | `DEBUG` | Set to `"true"` for detailed server-side logging |
  478. | `GODOT_MCP_ALLOWED_DIRS` | Optional. Restrict all project tools, project discovery and export destinations to these roots. Use `;` or `,` on Windows, and `:` or `,` on other systems. Existing symbolic links are resolved before checking access. When unset, any project root is allowed. |
  479. File and scene paths must stay within their project directory, including paths
  480. under symbolic links. These checks cover MCP tool arguments. Runtime evaluation
  481. and generated scripts run with the Godot process account's permissions, so use a
  482. separate account or container when executing untrusted code.
  483. ### Runtime log retention
  484. `game_get_logs` and `game_get_errors` accept optional `cursor` and `limit`
  485. arguments. The default page size is 200 lines, with a maximum of 500. Responses
  486. include `nextCursor`, `hasMore` and `dropped`. Pass `nextCursor` back to continue
  487. from the same position. Calls without a cursor continue from the previous call.
  488. Each stream retains the newest 2,000 lines, with at most 4,096 characters per line.
  489. If a cursor predates retained output, `dropped` is true. `get_debug_output` returns
  490. the retained streams and their starting offsets.
  491. ### Contributor validation
  492. Development and CI require Node.js 22.12 or later. The server runtime requirement
  493. remains the version specified in `package.json`.
  494. ```bash
  495. npm ci
  496. npm test
  497. npm audit --audit-level=moderate
  498. ```
  499. CI runs on Node.js 22 and 24 without publishing packages or deploying services.
  500. `npm test` builds the server first so executable-entry tests use current code.
  501. Tests include real MCP requests over the SDK's in-memory transport, filesystem
  502. boundary checks, symbolic link escapes, project scaffolding, schema validation
  503. and cursor pagination. Running an actual Godot project remains an integration
  504. check that requires an installed engine. Set `GODOT_SMOKE_PATH` to the full path
  505. of its console executable to enable the temporary-project headless smoke test.
  506. It creates a project, creates and edits a scene, reads it through MCP, and saves
  507. a second scene. The test removes its temporary files afterward.
  508. ## Architecture
  509. The server uses two communication channels:
  510. 1. **Headless CLI** - For operations that don't need a running game (scene reading, modification, resource creation). Runs Godot with `--headless --script godot_operations.gd <operation> <json_params>`.
  511. 2. **TCP Socket** - For runtime interaction with a running game. The `mcp_interaction_server.gd` autoload listens on port 9090 and processes JSON commands sent by the TypeScript MCP server.
  512. ### Source layout
  513. | Path | Description |
  514. |------|-------------|
  515. | `src/index.ts` | MCP server, tool definitions, and all handlers |
  516. | `src/utils.ts` | Pure utility functions (parameter mapping, validation, error helpers) |
  517. | `src/scripts/godot_operations.gd` | Headless GDScript operations runner |
  518. | `src/scripts/mcp_interaction_server.gd` | TCP interaction server autoload |
  519. | `tests/` | Vitest test suite |
  520. ## Testing
  521. The project uses [Vitest](https://vitest.dev/) with 446 tests across 5 files:
  522. | File | Tests | What it covers |
  523. |------|-------|----------------|
  524. | `tests/utils.test.ts` | 31 | Parameter mappings, normalization, path validation, error responses, version detection |
  525. | `tests/tool-definitions.test.ts` | 163 | All 155 tools defined, schemas valid, names unique, descriptions < 80 chars |
  526. | `tests/handlers.test.ts` | 225 | Game command arg transforms, required-param validation, headless op path checks, source structure |
  527. | `tests/dotnet.test.ts` | 20 | .NET feature flag, .csproj generation, C# script template generation, identifier validation |
  528. | `tests/validate-script.test.ts` | 12 | GDScript diagnostic parsing + git-changed file collection |
  529. ```bash
  530. npm test # run once
  531. npm run test:watch # watch mode
  532. ```
  533. ## Example Prompts
  534. ```text
  535. "Run my Godot project and check for errors"
  536. "Eval this in my running game: return get_tree().current_scene.name"
  537. "Get the player's position in the running game"
  538. "Set the player's health to 100"
  539. "Read the test_level.tscn scene and show me the node tree"
  540. "Change the player's speed property in the player.tscn scene file"
  541. "List all .gd files in my project"
  542. "Connect the enemy's 'died' signal to the game manager's 'on_enemy_died' method"
  543. "Tween the camera's position to (0, 10, -5) over 2 seconds with ease-out"
  544. "Get performance metrics - what's my FPS and draw call count?"
  545. "Pause the game and take a screenshot"
  546. "Find all CharacterBody3D nodes in the scene"
  547. "Create a new Godot project called 'MyGame' and write a player script"
  548. "Create a new C# (.NET) Godot project and add a CharacterBody2D script"
  549. "Validate player.gd for errors"
  550. "Check all my changed GDScript files for syntax errors before I run the game"
  551. "Hold down the W key for 2 seconds to test walking"
  552. "Cast a ray from the player downward to check for ground"
  553. "Get the camera position and move it to look at the player"
  554. "Show me the latest error messages from the running game"
  555. ```
  556. ## License
  557. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  558. ## Credits
  559. - **Original project**: [godot-mcp](https://github.com/Coding-Solo/godot-mcp) by [Solomon Elias (Coding-Solo)](https://github.com/Coding-Solo) - provided the foundational MCP server architecture, headless operations system, and TCP interaction framework
  560. - **Extended by**: [Tugcan Topaloglu](https://github.com/tugcantopaloglu) - extended to 157 tools covering networking, 3D/2D rendering, UI controls, audio effects, animation trees, file I/O, runtime code execution, node manipulation, signals, project creation, camera control, physics, and comprehensive type conversion

Ratings and comments

Sign in to rate this skill.

Sign in

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