Randoloot/addons/godot_mcp_toolkit/README.md

Godot MCP Toolkit

A Godot 4.2+ editor plugin that runs a localhost WebSocket server so an AI coding assistant — Claude Code, or any MCP-compatible client — can create scenes, edit scripts, inspect nodes, and run playtests inside your editor. The plugin is half the stack: the companion npm package @npgamedev/godot-mcp-server is the bridge your assistant actually talks to.

Everything runs locally. Nothing leaves your machine.

Quick start

1. Enable the plugin: Project Settings → Plugins → Godot MCP Toolkit → check Active. The MCP dock appears in the bottom panel and the Output log prints [MCPServer] listening on 127.0.0.1:6550 (the port may land anywhere in 6550–6560; the dock names the live one). That line is the plugin's own WebSocket server inside the editor. The npm bridge is a separate process your MCP client starts later, and it dials this port.
2. Write the client config: Project → Tools → MCP Toolkit → Write .mcp.json creates the config at your project root. It runs the bridge through npx -y @npgamedev/godot-mcp-server, which fetches it on first connect, so there is no install step (Node.js 22 or newer required). If you would rather keep a fixed copy on the machine, npm install -g @npgamedev/godot-mcp-server works too. (Manual alternative: copy addons/godot_mcp_toolkit/.mcp.json.template to your project root and rename it .mcp.json.)
3. Connect: launch your MCP client from the project root. It discovers the plugin and authenticates automatically; the dock's peer count increments on connection.

If a step misfires, the troubleshooting guide has a 60-second checklist and a connectivity probe: https://github.com/NPGameDev/godot-mcp-toolkit/blob/main/docs/troubleshooting.md

Where things are

• The dock (bottom panel, "MCP") — server status and the bound port, connected peers, the read-only toggle, audit-log viewer, response limits, and .mcp.json health with a one-click fix.
• Project → Tools → MCP Toolkit — quick actions: write or open .mcp.json, regenerate the auth token, show the audit log, open the plugin's Project Settings. Also in the Command Palette (Ctrl+Shift+P).
• Info / Help (button in the dock) — connection details, the registered tool list, version compatibility, multi-instance guidance, and links, including a button that opens the shipped compatibility guide.

Read-only mode

For supervised environments (classrooms, CI, demos), flip the dock's read-only toggle (or set GODOT_MCP_READ_ONLY=1 in the .mcp.json env block). Every mutating tool is hidden from the agent. Turn it off and reconnect the client to restore full access — the tool list is decided at connect time.

Documentation

Shipped with this addon, in addons/godot_mcp_toolkit/docs/:

• compatibility.md — supported Godot versions, per-tool and headless matrices, degraded behavior, the C# (.NET editor) requirement, export stripping, and how to disable the plugin safely.
• security-recommendations.md — the security model and recommended client-side permission rules.
• extending.md — register your own MCP tools in GDScript (C# supported), with hot-reload, timeouts, and cancellation.
• multi-instance.md — several editors or git worktrees side by side.
• advanced_configuration.md — ports, limits, environment variables, macOS specifics.

The addon also bundles agent skills — a workflow skill and an extension-authoring skill — in addons/godot_mcp_toolkit/CompanionSkills/; copy a skill folder into your client's skills directory to use them.

On the web:

• Tool reference (every tool and operation, generated from the code): https://github.com/NPGameDev/godot-mcp-server/blob/main/docs/tool-reference/README.md
• Toolkit repository, issues, and full documentation: https://github.com/NPGameDev/godot-mcp-toolkit

Uninstalling

Disable via Project Settings → Plugins (a dialog offers to clean up .mcp.json), or remove the addon folder. If you delete the folder while the plugin is still enabled, the cleanup step cannot run — delete .mcp.json from your project root yourself. The shipped compatibility guide covers why you should not disable the plugin by hand-editing project.godot.

License

MIT: the full text travels with the addon in LICENSE. Third-party attributions are in ATTRIBUTIONS.md.

Trademarks

Godot and the Godot logo are trademarks of the Godot Foundation. This add-on is an independent community project with no affiliation with or endorsement from the Foundation, and it is not an official Godot product. The name describes what the add-on runs on: the Godot Engine.