better-godot

Better Godot MCP is a composite server that exposes a suite of Godot-focused tools via the MCP framework, optimized for AI agents. It aggregates actions to manage Godot projects, scenes, nodes, scripts, shaders, physics, audio, navigation, and more through a single, commandable MCP server. You can access tools like project, scenes, nodes, scripts, editor, setup, config, help, resources, input_map, signals, animation, tilemap, shader, physics, audio, navigation, and ui to perform common Godot operations in a token-efficient, tool-driven manner. Start the server using your preferred runner (Bun, npm/npx, or Docker) and then invoke the available tools through the MCP interface with the corresponding actions (e.g., project run, scenes list, nodes add, shader write). The tooling is designed to work with Godot 4.x project structures and relies on passing project_path to tools as parameters. Use the help tool on any tool to get full documentation and parameter schemas for that tool.

Prerequisites:

• Node.js (recommended for local development) or Docker for containerized use
• Bun (recommended for Bun-based execution as shown) or Docker installed on your system
• Access to a Godot 4.x project if you plan to run real project operations

Option A: Install and run via Bun (recommended in this repo)

1. Install Bun if you don’t have it: curl -fsSL https://bun.sh/install | bash
2. Install and run the MCP server via Bun (no global install required):
   • Create or edit a config file with the mcpServers entry for better-godot (see mcp_config example in this README)
   • Start the server using Bun as depicted in the config: bun x @n24q02m/better-godot-mcp@latest
3. Verify the server is running and accessible through your MCP client or tooling.

Option B: Run via Docker

1. Ensure Docker is installed and running.
2. Start the container using the example configuration in the README, mapping any needed project directories as required by your setup: docker run -i --rm --name mcp-godot n24q02m/better-godot-mcp:latest
3. Connect your MCP client to the running server using the configured server name (better-godot).

Option C: Other runners (npx/pnpm/yarn)

• You can also start with npx -y @n24q02m/better-godot-mcp@latest or via pnpm/yarn as documented in the README, and then connect through MCP tooling as usual.

Notes and tips:

• The project path is passed to tools via tool parameters (not environment variables) when using Docker; if running locally, ensure GODOT_PROJECT_PATH is set in your environment if you rely on it, but the tools typically accept project_path as a parameter.
• Environment variables GODOT_PROJECT_PATH and GODOT_PATH are optional; GODOT_PATH can be auto-detected if not set.
• This MCP server targets Godot 4.x project structures and uses text-based manipulation for .tscn files (no full Godot API access).
• If you encounter permission or filesystem issues in Docker mode, mount your project directory into the container accordingly and note Docker’s limited filesystem access.
• You can access full tool documentation at runtime via the help tool (e.g., help scenes) for parameter details and usage examples.