{
  "markdown": "# Godot MCP Server\n\n[![CI](https://github.com/sterion66/godot-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/sterion66/godot-mcp-server/actions/workflows/ci.yml)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nA comprehensive [FastMCP](https://github.com/jlowin/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.\n\n<!-- mcp-name: io.github.sterion66/godot -->\n\n[Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)\n\n**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](#workspace-setup-required).\n\n**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)](#godot-execution-environment).\n\n**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.\n\n**Symlinks:** `GODOT_MCP_ROOT` is resolved with symlinks followed; point it at a real directory you control.\n\n## Features\n\n### Project Management\n- Auto-detect Godot projects (`project.godot`); list all projects under the workspace (`godot_list_projects`)\n- Create new projects under the workspace (`godot_create_project`)\n- Parse project settings and configuration; list autoloads and editor plugin state (read-only for plugins)\n- Refresh project cache after changes\n\n### File Operations\n- Read/write scenes (`.tscn`), scripts (`.gd`), resources (`.tres`)\n- Create new scripts, scenes, resources from templates\n- Edit existing files with content replacement\n- Validate scene and script syntax\n\n### Code Generation\n- CharacterBody2D/3D movement controllers\n- State machine patterns\n- Custom resources\n- Node scripts with signals/exports\n\n### Asset Management\n- Discover assets by extension, pattern, glob\n- Find unused assets\n- Search file contents with regex\n- **Search & download from Godot Asset Library**\n- **Browse Godot repos on GitHub**\n\n### Runtime Integration\n- Find Godot executable\n- Check Godot version\n- Run game headless\n- Execute GDScript code\n- Read Godot logs\n- File watcher configuration\n\n## Installation\n\n```bash\n# From PyPI-style editable install (recommended for contributors)\npip install -e .\n\n# Or minimal deps only\npip install -r requirements.txt\n```\n\nConsole entry point (after `pip install -e .`): `godot-mcp-server` (same as `python godot_mcp_server.py`).\n\n## Workspace setup (required)\n\nThe 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.\n\n1. **Create the default folder** (once per machine):\n\n   ```bash\n   mkdir -p ~/godot-games\n   ```\n\n2. **Put every Godot game there** — each game is its own subdirectory containing `project.godot`, for example:\n\n   ```text\n   ~/godot-games/\n     my-platformer/     ← open this folder in your editor\n       project.godot\n       ...\n     another-game/\n       project.godot\n   ```\n\n3. **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.\n\n4. **Custom location:** Set an absolute path before starting the server:\n\n   ```bash\n   export GODOT_MCP_ROOT=\"/path/to/your/godot-games\"\n   python godot_mcp_server.py\n   ```\n\n   In Cursor / Claude / other MCP configs, add `env`:\n\n   ```json\n   \"env\": {\n     \"GODOT_MCP_ROOT\": \"/path/to/your/godot-games\"\n   }\n   ```\n\n   If unset, the default is **`$HOME/godot-games`**. The server creates that directory on startup if it does not exist.\n\n5. **Inspect at runtime:** call the tool `godot_get_workspace` or read the resource `project://workspace` to see the active workspace path.\n\nIf tools report that no project was found, your cwd is probably outside the workspace, or `project_path` points outside `GODOT_MCP_ROOT`.\n\n## Godot execution (environment)\n\nRunning 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.\n\n**Shipped configs (default yes):** every example JSON in this repo (`mcp_config.json`, `mcp_config.cursor.json`, etc.) includes:\n\n```json\n\"env\": {\n  \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n}\n```\n\nSo 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.\n\n**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).\n\n**Stricter setups:** delete `GODOT_MCP_ALLOW_GODOT_EXEC` from `env`, or set it to `0` / `false` / `no` / `off`, then restart the MCP client.\n\nAccepted “on” values: `1`, `true`, `yes`, `on` (case-insensitive). Call `godot_get_workspace` and check `godot_exec_allowed` to confirm.\n\n## Usage\n\n### CLI (stdio - for Claude Code/Cursor)\n```bash\npython godot_mcp_server.py\n```\n\n### HTTP Server\n```bash\npython godot_mcp_server.py --transport http --port 8765\n```\n\n## Configuration\n\nSet `GODOT_MCP_ROOT` in the MCP server `env` if you do not use the default `~/godot-games`. See [Workspace setup](#workspace-setup-required). Shipped snippets below include `GODOT_MCP_ALLOW_GODOT_EXEC`; see [Godot execution (environment)](#godot-execution-environment).\n\n**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.\n\n### Install in your editor\n\nExpand 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.\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\n**macOS / Linux (project or user config)** — Settings → MCP → *Add new global MCP server* **or** create `.cursor/mcp.json` in a project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"python3\",\n      \"args\": [\"godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      }\n    }\n  }\n}\n```\n\n**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`:\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"python\", \"C:\\\\path\\\\to\\\\godot-mcp-server\\\\godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      }\n    }\n  }\n}\n```\n\nMerge `GODOT_MCP_ROOT` into `env` if you do not use `~/godot-games` (see [Workspace setup](#workspace-setup-required)).\n\n</details>\n\n<details>\n<summary><strong>Visual Studio Code</strong></summary>\n\nUse 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"python3\",\n      \"args\": [\"godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      }\n    }\n  }\n}\n```\n\nUse an absolute path in `args` if the workspace folder is not the repo root.\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nEdit the app config file:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"python3\",\n      \"args\": [\"/absolute/path/to/godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong> (CLI)</summary>\n\nMerge into `~/.claude/settings.json` (or use `claude mcp add` if your CLI supports it — check `claude mcp --help`):\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"python3\",\n      \"args\": [\"godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      },\n      \"description\": \"Godot 4.x game development server\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Windsurf</strong> (Codeium)</summary>\n\n**macOS / Linux:** edit `~/.codeium/windsurf/mcp_config.json`, or use **CMD+SHIFT+P → “Windsurf: Configure MCP Servers”**.\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"python3\",\n      \"args\": [\"godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      },\n      \"description\": \"Godot 4.x game development - project, scenes, scripts, assets, runtime\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Roo Code</strong></summary>\n\nPaste into Roo’s MCP settings (project or global), same JSON shape as above. Repo copy: `roo_code_mcp.json`.\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"python3\",\n      \"args\": [\"godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      },\n      \"description\": \"Godot 4.x game dev - project, scenes, scripts, assets, runtime\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Generic JSON</strong> (any MCP host)</summary>\n\nMinimal stdio config — same as `mcp_config.json` in this repo:\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"command\": \"python3\",\n      \"args\": [\"godot_mcp_server.py\"],\n      \"env\": {\n        \"GODOT_MCP_ALLOW_GODOT_EXEC\": \"1\"\n      },\n      \"description\": \"Godot 4.x game development server - file ops, asset management, runtime integration\"\n    }\n  }\n}\n```\n\n</details>\n\n### Limits (DoS / abuse)\n\n- **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.\n- **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`).\n- **Asset Library IDs:** `asset_id` for `godot_get_asset_info` / `godot_download_asset` must be numeric digits only.\n\n### HTTP Mode (Remote)\n\nUse loopback unless you know what you are doing:\n\n```bash\npython godot_mcp_server.py --transport http --host 127.0.0.1 --port 8765\n```\n\nBinding to all interfaces (`--host 0.0.0.0`) logs a warning and exposes MCP to your LAN with **no authentication** in this server.\n\nThen use `serverUrl` instead of `command`:\n\n```json\n{\n  \"mcpServers\": {\n    \"godot\": {\n      \"serverUrl\": \"http://localhost:8765/mcp\"\n    }\n  }\n}\n```\n\n<details>\n<summary><strong>Why not duplicate HTTP + stdio?</strong></summary>\n\nOnly run **one** transport to the same project (stdio **or** HTTP), not both at once, to avoid conflicting MCP sessions.\n\n</details>\n\n## Tools Reference\n\n40 MCP tools are registered in `godot_mcp_server.py` (search for `@mcp.tool`). Summary:\n\n| Tool | Description |\n|------|-------------|\n| `godot_get_workspace` | Show MCP sandbox directory (`GODOT_MCP_ROOT`) |\n| `godot_find_project` | Locate project root (walk-up or workspace scan) |\n| `godot_list_projects` | List every `project.godot` under the workspace |\n| `godot_create_project` | Create `project.godot` + starter scene under the workspace |\n| `godot_get_project_info` | Get project details |\n| `godot_get_project_settings` | Parse project.godot (includes `editor_plugins_enabled` read-only) |\n| `godot_get_project_files` | List all project files |\n| `godot_refresh_project` | Rescan scenes/scripts/resources counts |\n| `godot_list_scenes` | List `.tscn` files |\n| `godot_list_scripts` | List `.gd` files |\n| `godot_list_resources` | List `.tres` files |\n| `godot_list_autoload` | List autoload singletons |\n| `godot_list_editor_plugins` | Installed addons vs enabled in project.godot (enable plugins in the Godot editor) |\n| `godot_find_assets` | Find by extension |\n| `godot_find_unused_files` | Find unreferenced assets |\n| `godot_find_by_pattern` | Glob pattern search |\n| `godot_search_content` | Regex search in files |\n| `godot_create_script` | Create new GDScript |\n| `godot_create_scene` | Create new scene |\n| `godot_create_resource` | Create new resource |\n| `godot_create_code_template` | Template scripts |\n| `godot_read_scene` | Parse scene file |\n| `godot_read_script` | Parse GDScript |\n| `godot_validate_scene` | Validate scene |\n| `godot_validate_script` | Validate syntax |\n| `godot_edit_file` | Replace content |\n| `godot_write_file` | Write file |\n| `godot_get_file_info` | File metadata |\n| `godot_find_godot_executable` | Locate Godot |\n| `godot_check_version` | Godot version |\n| `godot_run_game` | Run headless |\n| `godot_execute_script` | Run GDScript |\n| `godot_get_log` | Read logs |\n| `godot_watch_files` | Configure watcher |\n| `godot_get_node_info` | Node type hints |\n| `godot_generate_uid` | Generate UID |\n| `godot_search_assetlib` | Search Asset Library |\n| `godot_get_asset_info` | Asset details |\n| `godot_download_asset` | Download / extract asset (promotes nested `addons/`) |\n| `godot_browse_github` | Search GitHub |\n\n**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.\n\n## Resources\n\n| Resource | URI | Description |\n|----------|-----|-------------|\n| Project Info | `project://info` | Basic project info |\n| Project Overview | `project://overview` | File counts |\n| Workspace | `project://workspace` | MCP sandbox path (`GODOT_MCP_ROOT`) |\n| Runtime | `project://runtime` | Godot version + workspace path |\n\n## Examples\n\n### Create a Platformer Player\n```python\n# Using template\ncreate_code_template(\"character_body_2d\", \"Player\")\n```\n\n### Find Assets\n```python\n# All PNG files\nfind_assets([\".png\", \".jpg\"])\n\n# Unused assets\nfind_unused_files()\n```\n\n### Search Asset Library\n```python\nsearch_assetlib(\"platformer\")\n# => [{title: \"PlatformerController2D\", ...}]\n\nget_asset_info(\"1062\")\n# => {title, author, description, license, download_url}\n```\n\n### Run Game Headless\n\nRequires `GODOT_MCP_ALLOW_GODOT_EXEC` (included in the shipped MCP JSON configs).\n\n```python\nrun_game(headless=True, quit_after_seconds=30)\n```\n\n## Requirements\n\n- Python 3.10+\n- Dependencies: `fastmcp`, `urllib3` (see `pyproject.toml`)\n\n## Development\n\n```bash\npip install -e \".[dev]\"\nruff check godot_mcp_server.py tests\npytest\n```\n\nContinuous integration runs on **Python 3.10–3.14** (see `.github/workflows/ci.yml`). [Dependabot](.github/dependabot.yml) opens weekly PRs for pip and GitHub Actions.\n\nOptional: `pip install pre-commit && pre-commit install` uses `.pre-commit-config.yaml`.\n\n## Publish to GitHub\n\n1. Create an empty repository on GitHub (no README/license if you already have them locally), e.g. `godot-mcp-server`.\n2. Add the remote and push:\n\n```bash\ncd /path/to/godot-mcp-server\ngit remote add origin https://github.com/YOUR_USER/godot-mcp-server.git\ngit push -u origin main\n```\n\nOr with [GitHub CLI](https://cli.github.com/): `gh repo create godot-mcp-server --public --source=. --remote=origin --push`\n\nAfter 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.\n\n## License\n\n[MIT](LICENSE)",
  "bytes": 16178,
  "sha": "e4d167fc8686eafb6a5b2c2b89381bb176de4c8d550149fdecdce0cb87317702",
  "repo_slug": "sterion66/godot-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sterion66_godot_6bab9a4e/readme"
}