Godot MCP (Model Context Protocol)

A comprehensive integration between Godot Engine and AI assistants using the Model Context Protocol (MCP). This plugin allows AI assistants to interact with your Godot projects, providing powerful capabilities for code assistance, scene manipulation, and project management.

Features

• Full Godot Project Access: AI assistants can access and modify scripts, scenes, nodes, and project resources
• Two-way Communication: Send project data to AI and apply suggested changes directly in the editor
• Capability-Aware Editing: Patch application is scoped to an allowlisted set of directories, file types, and critical assets for safer automation
• Project Indexing & Query: Cached project map with glob-style queries for quick discovery of files and directories
• Node Workflow Enhancements: Rename nodes, manage group membership, and enumerate group contents with full undo/redo support
• Input Map Automation: Inspect, add, and remove input actions or individual input events without leaving the editor
• Headless Execution & Profiling: Launch deterministic headless runs, capture editor performance snapshots, and manage plugin state with audit-friendly logs
• Command Categories:
  • Node Commands: Create, modify, and manage nodes in your scenes
  • Script Commands: Edit, analyze, and create GDScript files
  • Scene Commands: Manipulate scenes and their structure
  • Physics Configuration: Configure physics bodies, areas, and joints with transaction-aware updates
  • CSG & GridMap Helpers: Prototype boolean geometry and GridMap layouts with undo-safe editing primitives
  • Project Commands: Access project settings and resources
  • Editor Commands: Control various editor functionality
  • XR Commands: Inspect interfaces, initialize platforms, and persist XR project settings
  • Multiplayer Commands: Spin up ENet/WebSocket/WebRTC peers and spawn network-ready scenes
  • Compression Commands: Manage GPU texture presets, import profiles, and batch reimports

Quick Setup

1. Clone the Repository

git clone https://github.com/ee0pdt/godot-mcp.git
cd godot-mcp

2. Set Up the MCP Server

cd server
npm install
npm run build
# Return to project root
cd ..

3. Set Up Claude Desktop

1. Edit or create the Claude Desktop config file:

   # For macOS
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Add the following configuration (or use the included claude_desktop_config.json as a reference):

   {
     "mcpServers": {
       "godot-mcp": {
    	 "command": "node",
    	 "args": [
    	   "PATH_TO_YOUR_PROJECT/server/dist/index.js"
    	 ],
    	 "env": {
    	   "MCP_TRANSPORT": "stdio"
    	 }
       }
     }
   }

   Note: Replace PATH_TO_YOUR_PROJECT with the absolute path to where you have this repository stored.

3. Restart Claude Desktop

4. Open the Example Project in Godot

1. Open Godot Engine
2. Select "Import" and navigate to the cloned repository
3. Open the project.godot file
4. The MCP plugin is already enabled in this example project

Using MCP with Claude

After setup, you can work with your Godot project directly from Claude using natural language. Here are some examples:

Example Prompts

@mcp godot-mcp read godot://script/current

I need help optimizing my player movement code. Can you suggest improvements?

@mcp godot-mcp run get-scene-tree

Add a cube in the middle of the scene and then make a camera that is looking at the cube.

@mcp godot-mcp read godot://scene/current

Create an enemy AI that patrols between waypoints and attacks the player when in range.

Natural Language Tasks Claude Can Perform

• "Create a main menu with play, options, and quit buttons"
• "Add collision detection to the player character"
• "Implement a day/night cycle system"
• "Refactor this code to use signals instead of direct references"
• "Debug why my player character falls through the floor sometimes"

Available Resources and Commands

Resource Endpoints:

• godot://script/current - The currently open script
• godot://scene/current - The currently open scene
• godot://project/info - Project metadata and settings
• godot://project/index - Cached project file and directory index snapshot
• godot://audio/buses - Project audio bus layout, routing metadata, and effect stacks
• godot://physics/world - Live snapshot of 2D/3D physics spaces with per-space gravity, body/area/joint inventories, and configuration metadata.
• godot://animation/state-machines - Inspect AnimationTree graphs, blend spaces, and transitions for the active scene.
• godot://animation/tracks - Read AnimationPlayer timelines, tracks, and keyframes with keyframe metadata.
• godot://xr/interfaces - Report available XR interfaces, initialization state, and capabilities.
• godot://multiplayer/state - Summarize the active SceneTree multiplayer peer, connectivity, and authority configuration.
• godot://assets/compression-presets - Surface configured texture compression presets and import profiles.

Upcoming Resource Endpoints (sourced from godotengine/godot)

• godot://ui/theme - Surface the currently applied UI Theme resources, styles, and fonts for audit.

Command Categories:

Node Commands

• create_node - Create a new node under a specified parent path
• delete_node - Delete a node from the edited scene
• update_node_property - Change a node property with undo support
• get_node_properties - Inspect every exposed property on a node
• list_nodes - Enumerate the children of a node in the scene tree
• rename_node - Rename a node while preserving undo history
• add_node_to_group - Add a node to a named group (optionally persisting to the scene file)
• remove_node_from_group - Remove a node from a group with undo/redo
• create_theme_override - Author Control theme overrides with undo-safe transactions
• wire_signal_handler - Connect node signals to scripted methods with optional stub generation
• layout_ui_grid - Apply column-based layouts to Control containers with consistent spacing
• validate_accessibility - Inspect Control nodes for missing focus, labels, or accessible descriptions
• list_node_groups - List all groups the node currently belongs to
• list_nodes_in_group - Enumerate nodes that are members of a group in the edited scene

Script Commands

• create_script - Create a new GDScript file and optionally attach it to a node
• edit_script - Replace the contents of an existing script file
• get_script - Fetch a script by file path or by attached node
• create_script_template - Generate a GDScript skeleton with common callbacks

Scene Commands

• create_scene - Create a new scene with an optional root node type
• save_scene - Save the currently edited scene to disk
• open_scene - Open a scene in the editor
• get_current_scene - Report information about the open scene
• get_project_info - Return the project name, version, and active scene details
• create_resource - Create and serialize a new resource asset
• begin_scene_transaction - Start a named transaction for batching scene edits
• commit_scene_transaction - Commit a pending scene transaction
• rollback_scene_transaction - Roll back a transaction (even after commit)
• list_scene_transactions - List transaction identifiers that are currently tracked
• configure_physics_body - Adjust PhysicsBody2D/3D properties with undo/redo
• configure_physics_area - Update Area2D/Area3D monitoring, gravity, and masks
• configure_physics_joint - Rewire Joint2D/3D connections and constraint limits
• link_joint_bodies - Connect joints to specific physics bodies and optionally tweak constraint settings
• rebuild_physics_shapes - Regenerate CollisionShape3D resources from Mesh nodes or assets
• profile_physics_step - Capture PhysicsServer and Performance metrics for quick diagnostics
• configure_csg_shape - Tweak CSG combiners and primitives with undo/redo support
• configure_material_resource - Create/update Material resources, apply glslang shader code, bind lightmapper textures, and persist meshoptimizer metadata
• paint_gridmap_cells - Stamp MeshLibrary items into GridMap coordinates in batches
• clear_gridmap_cells - Remove items from GridMap cells while preserving undo history
• author_audio_stream_player - Create or configure AudioStreamPlayer nodes with stream assignments and playback settings
• author_interactive_music_graph - Build or update AudioStreamInteractive resources with layered clips and transition logic
• generate_dynamic_music_layer - Layer a new clip onto an interactive music resource with configurable entry/exit transitions
• analyze_waveform - Produce amplitude, RMS, and crest factor summaries for AudioStream resources with optional envelope bins
• batch_import_audio_assets - Apply import presets or parameter overrides to audio files and trigger a batch reimport

Animation Commands

• list_animation_players - Enumerate AnimationPlayer nodes, active playback settings, and contained animations.
• describe_animation_tracks - Inspect AnimationPlayer track configurations with optional keyframe timing and values.
• describe_animation_state_machines - Summarize AnimationTree state machines, nested graphs, and transition metadata.
• edit_animation - Apply structured operations to animation resources (tracks, keys, properties) with undo/redo support.
• configure_animation_tree - Update AnimationTree properties, blend parameters, and state playback targets.
• bake_skeleton_pose - Capture Skeleton2D/3D poses into an Animation resource at a specified timestamp.
• generate_tween_sequence - Build Animation timelines from tween-style step definitions.
• sync_particles_with_animation - Align particle emission properties and animation keys with an animation clip.

Navigation Commands

• list_navigation_maps - Summarize NavigationRegion2D/3D nodes and their resources
• list_navigation_agents - Inspect NavigationAgent2D/3D avoidance and target settings
• bake_navigation_region - Trigger baking on a navigation region (threaded by default)
• update_navigation_region - Change navigation region node properties with undo/redo
• update_navigation_resource - Edit NavigationPolygon or NavigationMesh resource properties
• update_navigation_agent - Adjust NavigationAgent parameters with undo/redo
• synchronize_navmesh_with_tilemap - Rebake TileMap navigation layers and optional navigation regions

Project Commands

• refresh_project_index - Rebuild the cached project index snapshot
• query_project_index - Query the cached project index with glob patterns
• list_input_actions - List every input action and associated events
• add_input_action - Create or overwrite an input action definition
• remove_input_action - Delete an input action from the project settings
• add_input_event_to_action - Register an additional event on an existing input action
• remove_input_event_from_action - Remove an input event by index or matching fields
• configure_input_action_context - Batch manage related input actions and persist context metadata
• list_audio_buses - Enumerate the audio bus graph with volume, routing, and effect status
• configure_audio_bus - Adjust audio bus volume, routing, and effect enablement with optional persistence
• configure_project_setting - Guard-railed ProjectSettings writes with type-aware validation and optional persistence

XR Commands

• list_xr_interfaces - Enumerate XR interfaces, initialization state, and capabilities exposed by the project build.
• initialize_xr_interface - Initialize a named XR interface and optionally promote it to the primary interface.
• shutdown_xr_interface - Gracefully end the XR session for a specific interface and release resources.
• save_xr_project_settings - Persist XR-related ProjectSettings entries for deterministic editor configuration.

Multiplayer Commands

• get_multiplayer_state - Capture the SceneTree multiplayer snapshot including connected peers and authority metadata.
• create_multiplayer_peer - Configure ENet, WebSocket, or WebRTC peers in server/client mode for playtesting.
• teardown_multiplayer_peer - Disconnect and clear the active multiplayer peer returning the scene to single-player mode.
• spawn_multiplayer_scene - Instantiate a PackedScene and optionally assign multiplayer authority for quick session setup.

Compression Commands

• configure_texture_compression - Apply GPU compression options scoped to a platform and optionally save to disk.
• batch_reimport_textures - Reimport a batch of textures so new compression presets are applied consistently.
• create_texture_import_preset - Register reusable import presets for ASTC/KTX/WebP oriented workflows.
• list_texture_compression_settings - Inspect the current compression presets and import settings stored in ProjectSettings.

Rendering Commands

• generate_material_variant - Duplicate a Material resource, apply property and shader overrides, and optionally save it to disk.
• compile_shader_preview - Compile Godot shader source and surface uniform/default texture metadata without touching files.
• unwrap_lightmap_uv2 - Invoke ArrayMesh lightmap unwrapping for a Mesh resource or MeshInstance3D node with optional saving.
• optimize_mesh_lods - Produce simplified meshes for requested LOD ratios and optionally assign or persist the generated meshes.
• configure_environment - Update Environment ambient light, fog, sky, and sun scattering properties with undo transactions.
• preview_environment_sun_settings - Inspect current fog sun values and preview overrides before committing configuration changes.

Patch Commands

• preview_patch - Preview a diff before it is applied
• apply_patch - Apply a previously previewed diff (requires admin approval)
• cancel_patch - Discard a pending diff preview

Permission Commands

• list_permission_escalations - List pending and resolved permission escalation requests
• resolve_permission_escalation - Approve or deny a recorded escalation request (requires admin approval)

Editor Commands

• execute_editor_script - Run arbitrary GDScript in the editor context (requires admin approval)
• run_godot_headless - Launch the Godot editor binary headlessly and capture combined output for deterministic test runs
• capture_editor_profile - Gather CPU, rendering, and memory metrics from the active editor session
• manage_editor_plugins - Enable or disable project addons with optional persistence and structured logging
• snapshot_scene_state - Capture the edited scene tree, node metadata, and key properties for pre-change review

Planned Command Expansions (roadmap)

• Animation & VFX (delivered): edit_animation, configure_animation_tree, bake_skeleton_pose, generate_tween_sequence, sync_particles_with_animation.
• Physics & Navigation: configure_physics_body, link_joint_bodies, rebuild_physics_shapes, profile_physics_step, synchronize_navmesh_with_tilemap.
• UI & Interaction: create_theme_override, configure_input_action_context, wire_signal_handler, layout_ui_grid, validate_accessibility.
• Audio & Media: configure_audio_bus, analyze_waveform, batch_import_audio_assets.
• Rendering & Assets (delivered): generate_material_variant, compile_shader_preview, unwrap_lightmap_uv2, optimize_mesh_lods, configure_environment, preview_environment_sun_settings.
• Project & Editor Automation (delivered): configure_project_setting, run_godot_headless, capture_editor_profile, manage_editor_plugins, snapshot_scene_state.

Command Roles & Escalations

Every tool is tagged with a required role that indicates the level of trust needed to run it:

• read – Safe, read-only commands that never mutate project state.
• edit – Commands that edit project files or the scene tree under the existing capability allowlist.
• admin – High-risk commands that can execute arbitrary code or bypass guardrails.

The MCP server automatically records an escalation request for any command whose required role is not in the default auto-approved set (currently read and edit). When an escalation is required, the tool returns the escalation identifier along with a suggested natural-language prompt that a human reviewer can use to approve the action. Reviewers can inspect and resolve queued requests via the list_permission_escalations and resolve_permission_escalation tools.

Commands that currently require admin approval include:

• apply_patch
• execute_editor_script
• resolve_permission_escalation

Troubleshooting

Connection Issues

• Ensure the plugin is enabled in Godot's Project Settings
• Check the Godot console for any error messages
• Verify the server is running when Claude Desktop launches it

Plugin Not Working

• Reload Godot project after any configuration changes
• Check for error messages in the Godot console
• Make sure all paths in your Claude Desktop config are absolute and correct

Adding the Plugin to Your Own Godot Project

If you want to use the MCP plugin in your own Godot project:

1. Copy the addons/godot_mcp folder to your Godot project's addons directory
2. Open your project in Godot
3. Go to Project > Project Settings > Plugins
4. Enable the "Godot MCP" plugin

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation

For more detailed information, check the documentation in the docs folder:

• Getting Started
• Installation Guide
• Command Reference
• Architecture

License

This project is licensed under the MIT License - see the LICENSE file for details.