Setup

Better Godot MCP — Manual Setup Guide

Note: Plugin install (Method 1) uses stdio mode — no auth required for godot. The previous default of HTTP transport has been changed to stdio. If you relied on HTTP mode, set MCP_TRANSPORT=http or pass --http flag.

Method overview

This plugin defaults to stdio via plugin install (uvx/npx) — the simplest path and the one this guide covers in full. It also ships Docker images (:stdio and :http targets) and supports HTTP transport (MCP_TRANSPORT=http / --http) for self-hosting. What it does not offer (unlike better-notion-mcp/better-email-mcp/better-telegram-mcp) is a hosted remote-relay/OAuth mode — HTTP here is self-host only.

For comparison, the other 6 plugins in this stack (better-notion-mcp, better-email-mcp, better-telegram-mcp, wet-mcp, mnemo-mcp, imagine-mcp) document 3 methods:

1. Default — Plugin install (uvx/npx) stdio
2. Fallback — Docker stdio (Windows/macOS PATH issues)
3. Recommended — Docker HTTP (multi-device, OAuth/relay form, claude.ai web)

⚠️ Mutually exclusive — pick ONE per plugin: Do NOT stack /plugin install AND a user mcpServers override (Docker stdio or HTTP) — both would load simultaneously and create duplicate entries (plugin’s npx/uvx stdio + your override). Plugin matching is by endpoint (URL or command string) per CC docs, not by name — and npx/uvx ≠ docker ≠ HTTP URL, so all three are distinct endpoints. Choosing the Docker stdio or HTTP self-host path means losing the plugin’s skills/agents/hooks/commands. For full plugin features, use the default plugin install (Method 1) documented below.

Prerequisites

• Node.js >= 24.14.1
• Godot Engine 4.x installed (required for run, stop, export actions; optional for scene/script editing)
• A Godot 4.x project with a project.godot file

Method 1: Claude Code Plugin (Recommended)

Credential prompts at install

When you run /plugin install, Claude Code prompts you for the following credentials (declared in userConfig per CC docs). Sensitive values are stored in your system keychain and persist across /plugin update:

Field	Required	Where to obtain
GODOT_PATH	Optional	Absolute path to Godot 4.x binary; auto-detect from PATH if empty
GODOT_PROJECT_PATH	Optional	Default project root (can override per tool call)

Steps

1. Open Claude Code in your terminal.
2. Run:

   /plugin marketplace add n24q02m/claude-plugins
   /plugin install better-godot-mcp@n24q02m-plugins

3. The plugin auto-configures the MCP server in stdio mode — no prompts, no env vars required, it just works.

Optionally set GODOT_PROJECT_PATH to point at your Godot project directory; otherwise pass project_path per tool call.

Environment Variable Reference

Variable	Required	Default	Description
GODOT_PROJECT_PATH	No	—	Default Godot project directory. Each tool call can also pass project_path as a parameter.
GODOT_PATH	No	Auto-detected	Explicit path to the Godot binary. If not set, the server searches PATH and common install locations (Windows, macOS, Linux).
MCP_TRANSPORT	No	stdio	Set to http to run in HTTP mode (advanced; not in scope of this guide). The --http CLI flag is equivalent.
PORT	No	0 (auto)	HTTP port when MCP_TRANSPORT=http. Set explicitly when you need a stable port.

Troubleshooting

Server starts but tools fail with “project not found”

• Ensure your Godot project has a project.godot file at its root.
• Set GODOT_PROJECT_PATH to the directory containing project.godot, or pass project_path in each tool call.

Godot binary not detected

• Install Godot 4.x and ensure it is on your PATH, or set GODOT_PATH to the full path of the Godot executable.
• Use the config tool with action detect_godot to see where the server is looking.

Docker: “permission denied” or empty file listings

• Ensure the volume mount path is correct: -v /absolute/path:/project.
• On Linux, you may need to add :z to the mount flag for SELinux: -v /path:/project:z.

npx: “command not found” or old version

• Verify Node.js >= 24.14.1: node --version.
• Clear the npx cache: npx --yes clear-npx-cache or use @latest tag: npx -y @n24q02m/better-godot-mcp@latest.

Tools return errors about Godot 3.x

• This server requires Godot 4.x project structure. Godot 3.x projects are not supported.