Godot MCP Server

A comprehensive FastMCP server for Godot 4.x game development. Provides tooling for AI-assisted workflows: project management, file operations, asset discovery, GDScript development, and optional Godot execution.

Contributing · Security

Security model: All Godot projects, file writes, and Asset Library downloads are restricted to a single workspace directory on your machine (default ~/godot-games). The server refuses paths outside that tree. See Workspace setup.

Code execution: godot_run_game and godot_execute_script require GODOT_MCP_ALLOW_GODOT_EXEC in the server environment. The shipped MCP JSON configs set it to 1 so these tools work after copy-paste. Running python godot_mcp_server.py without that env still leaves execution off until you export it. To lock down an IDE install, remove the variable or set it to 0. See Godot execution (environment).

HTTP transport: Binding to 0.0.0.0 or :: exposes the MCP server on all network interfaces; prefer 127.0.0.1 unless you use a firewall or VPN.

Symlinks: GODOT_MCP_ROOT is resolved with symlinks followed; point it at a real directory you control.

Features

Project Management

• Auto-detect Godot projects (project.godot); list all projects under the workspace (godot_list_projects)
• Create new projects under the workspace (godot_create_project)
• Parse project settings and configuration; list autoloads and editor plugin state (read-only for plugins)
• Refresh project cache after changes

File Operations

• Read/write scenes (.tscn), scripts (.gd), resources (.tres)
• Create new scripts, scenes, resources from templates
• Edit existing files with content replacement
• Validate scene and script syntax

Code Generation

• CharacterBody2D/3D movement controllers
• State machine patterns
• Custom resources
• Node scripts with signals/exports

Asset Management

• Discover assets by extension, pattern, glob
• Find unused assets
• Search file contents with regex
• Search & download from Godot Asset Library
• Browse Godot repos on GitHub

Runtime Integration

• Find Godot executable
• Check Godot version
• Run game headless
• Execute GDScript code
• Read Godot logs
• File watcher configuration

Installation

# From PyPI-style editable install (recommended for contributors)
pip install -e .

# Or minimal deps only
pip install -r requirements.txt

Console entry point (after pip install -e .): godot-mcp-server (same as python godot_mcp_server.py).

Workspace setup (required)

The MCP server only operates on Godot projects that live under one root folder. This keeps assistants from reading or writing arbitrary paths on your system.

1. Create the default folder (once per machine):

   mkdir -p ~/godot-games
   

2. Put every Godot game there — each game is its own subdirectory containing project.godot, for example:

   ~/godot-games/
     my-platformer/     ← open this folder in your editor
       project.godot
       ...
     another-game/
       project.godot
   

3. Open your IDE workspace inside ~/godot-games/.../your-game (or a parent folder under ~/godot-games) so the MCP process can discover project.godot from the current working directory.

4. Custom location: Set an absolute path before starting the server:

   export GODOT_MCP_ROOT="/path/to/your/godot-games"
   
   

... View full README on GitHub