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):

   bash

   Copy

   mkdir -p ~/godot-games
   

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

   text

   Copy

   ~/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:

   server.ts

   Copy

   export GODOT_MCP_ROOT="/path/to/your/godot-games"
   python godot_mcp_server.py
   

   In Cursor / Claude / other MCP configs, add env:

   json

   Copy

   "env": {
     "GODOT_MCP_ROOT": "/path/to/your/godot-games"
   }
   

   If unset, the default is $HOME/godot-games. The server creates that directory on startup if it does not exist.

5. Inspect at runtime: call the tool godot_get_workspace or read the resource project://workspace to see the active workspace path.

If tools report that no project was found, your cwd is probably outside the workspace, or project_path points outside GODOT_MCP_ROOT.

Godot execution (environment)

Running the game or executing GDScript runs code as your user (same as starting Godot from a terminal). The server only enables godot_run_game / godot_execute_script when GODOT_MCP_ALLOW_GODOT_EXEC is set to an accepted “on” value.

Shipped configs (default yes): every example JSON in this repo (mcp_config.json, mcp_config.cursor.json, etc.) includes:

"env": {
  "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}

So if you copy one of those into your IDE, execution is allowed without extra steps. Merge other keys (e.g. GODOT_MCP_ROOT) into the same env object.

CLI without MCP config: running python godot_mcp_server.py does not set this variable; execution tools stay blocked until you export GODOT_MCP_ALLOW_GODOT_EXEC=1 (or use a wrapper script).

Stricter setups: delete GODOT_MCP_ALLOW_GODOT_EXEC from env, or set it to 0 / false / no / off, then restart the MCP client.

Accepted “on” values: 1, true, yes, on (case-insensitive). Call godot_get_workspace and check godot_exec_allowed to confirm.

Usage

CLI (stdio - for Claude Code/Cursor)

python godot_mcp_server.py

HTTP Server

python godot_mcp_server.py --transport http --port 8765

Configuration

Set GODOT_MCP_ROOT in the MCP server env if you do not use the default ~/godot-games. See Workspace setup. Shipped snippets below include GODOT_MCP_ALLOW_GODOT_EXEC; see Godot execution (environment).

Path to the server: Examples use "args": ["godot_mcp_server.py"] assuming the MCP process runs with its working directory at the folder that contains the script (e.g. you cloned this repo). If the server fails to start, replace that with the absolute path to godot_mcp_server.py on your machine.

Install in your editor

Expand a section and paste the JSON into the file your tool expects. The same godot server block is in the repo as mcp_config.*.json for copy-paste.

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "python", "C:\\path\\to\\godot-mcp-server\\godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["/absolute/path/to/godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development - project, scenes, scripts, assets, runtime"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game dev - project, scenes, scripts, assets, runtime"
    }
  }
}