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

   mkdir -p ~/godot-games
   

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

   text

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

   bash

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

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

   json

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

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

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.

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.

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

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

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

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

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:

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

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