godot-mcp-server 1.0.0

FastMCP server for Godot 4.x — AI-assisted projects, files, assets, and GDScript

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"
   python godot_mcp_server.py
   

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

   "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.

Cursor

macOS / Linux (project or user config) — Settings → MCP → Add new global MCP server or create .cursor/mcp.json in a project root:

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

Windows — if python is not on PATH for the MCP host, use the launcher or full path to python.exe, and prefer an absolute path in args:

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

Merge GODOT_MCP_ROOT into env if you do not use ~/godot-games (see Workspace setup).

Visual Studio Code

Use the MCP / agent settings your VS Code build provides (often Settings → MCP or a project .vscode/mcp.json, depending on version and extensions). Paste the same structure as Cursor:

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

Use an absolute path in args if the workspace folder is not the repo root.

Claude Desktop

Edit the app config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop after saving.

Claude Code (CLI)

Merge into ~/.claude/settings.json (or use claude mcp add if your CLI supports it — check claude mcp --help):

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

Windsurf (Codeium)

macOS / Linux: edit ~/.codeium/windsurf/mcp_config.json, or use CMD+SHIFT+P → “Windsurf: Configure MCP Servers”.

{
  "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"
    }
  }
}

Roo Code

Paste into Roo’s MCP settings (project or global), same JSON shape as above. Repo copy: roo_code_mcp.json.

{
  "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"
    }
  }
}

Generic JSON (any MCP host)

Minimal stdio config — same as mcp_config.json in this repo:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server - file ops, asset management, runtime integration"
    }
  }
}

Limits (DoS / abuse)

• Regex search (godot_search_content): Pattern length capped; match list capped; files larger than 2 MiB are skipped. Malicious regex can still be expensive—keep patterns simple.
• Asset zip download: Maximum download size, per-file uncompressed size, total uncompressed size, and file count are enforced before extraction (see constants near the top of godot_mcp_server.py).
• Asset Library IDs: asset_id for godot_get_asset_info / godot_download_asset must be numeric digits only.

HTTP Mode (Remote)

Use loopback unless you know what you are doing:

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

Binding to all interfaces (--host 0.0.0.0) logs a warning and exposes MCP to your LAN with no authentication in this server.

Then use serverUrl instead of command:

{
  "mcpServers": {
    "godot": {
      "serverUrl": "http://localhost:8765/mcp"
    }
  }
}

Why not duplicate HTTP + stdio?

Only run one transport to the same project (stdio or HTTP), not both at once, to avoid conflicting MCP sessions.

Tools Reference

40 MCP tools are registered in godot_mcp_server.py (search for @mcp.tool). Summary:

Tool	Description
godot_get_workspace	Show MCP sandbox directory (GODOT_MCP_ROOT)
godot_find_project	Locate project root (walk-up or workspace scan)
godot_list_projects	List every project.godot under the workspace
godot_create_project	Create project.godot + starter scene under the workspace
godot_get_project_info	Get project details
godot_get_project_settings	Parse project.godot (includes editor_plugins_enabled read-only)
godot_get_project_files	List all project files
godot_refresh_project	Rescan scenes/scripts/resources counts
godot_list_scenes	List .tscn files
godot_list_scripts	List .gd files
godot_list_resources	List .tres files
godot_list_autoload	List autoload singletons
godot_list_editor_plugins	Installed addons vs enabled in project.godot (enable plugins in the Godot editor)
godot_find_assets	Find by extension
godot_find_unused_files	Find unreferenced assets
godot_find_by_pattern	Glob pattern search
godot_search_content	Regex search in files
godot_create_script	Create new GDScript
godot_create_scene	Create new scene
godot_create_resource	Create new resource
godot_create_code_template	Template scripts
godot_read_scene	Parse scene file
godot_read_script	Parse GDScript
godot_validate_scene	Validate scene
godot_validate_script	Validate syntax
godot_edit_file	Replace content
godot_write_file	Write file
godot_get_file_info	File metadata
godot_find_godot_executable	Locate Godot
godot_check_version	Godot version
godot_run_game	Run headless
godot_execute_script	Run GDScript
godot_get_log	Read logs
godot_watch_files	Configure watcher
godot_get_node_info	Node type hints
godot_generate_uid	Generate UID
godot_search_assetlib	Search Asset Library
godot_get_asset_info	Asset details
godot_download_asset	Download / extract asset (promotes nested addons/)
godot_browse_github	Search GitHub

Editor plugins: this server does not write [editor_plugins] in project.godot (avoids conflicting with an open editor). Install addons via tools above; the user enables plugins in Project Settings → Plugins in Godot; use godot_list_editor_plugins to verify.

Resources

Resource	URI	Description
Project Info	project://info	Basic project info
Project Overview	project://overview	File counts
Workspace	project://workspace	MCP sandbox path (GODOT_MCP_ROOT)
Runtime	project://runtime	Godot version + workspace path

Examples

Create a Platformer Player

# Using template
create_code_template("character_body_2d", "Player")

Find Assets

# All PNG files
find_assets([".png", ".jpg"])

# Unused assets
find_unused_files()

Search Asset Library

search_assetlib("platformer")
# => [{title: "PlatformerController2D", ...}]

get_asset_info("1062")
# => {title, author, description, license, download_url}

Run Game Headless

Requires GODOT_MCP_ALLOW_GODOT_EXEC (included in the shipped MCP JSON configs).

run_game(headless=True, quit_after_seconds=30)

Requirements

• Python 3.10+
• Dependencies: fastmcp, urllib3 (see pyproject.toml)

Development

pip install -e ".[dev]"
ruff check godot_mcp_server.py tests
pytest

Continuous integration runs on Python 3.10–3.14 (see .github/workflows/ci.yml). Dependabot opens weekly PRs for pip and GitHub Actions.

Optional: pip install pre-commit && pre-commit install uses .pre-commit-config.yaml.

Publish to GitHub

1. Create an empty repository on GitHub (no README/license if you already have them locally), e.g. godot-mcp-server.
2. Add the remote and push:

cd /path/to/godot-mcp-server
git remote add origin https://github.com/YOUR_USER/godot-mcp-server.git
git push -u origin main

Or with GitHub CLI: gh repo create godot-mcp-server --public --source=. --remote=origin --push

After the first push, CI runs on every push and PR. Replace sterion66 in the README badge URLs if you use a different account or organization.

License

MIT