Godot MCP - Full Control

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