godot-mcp

MCP server for Godot 4 — connect external clients to the open editor to read and edit projects.

172 tools · Godot 4.4+ · Node.js 18+

Repo: https://github.com/youssof20/godot-mcp

Documentation: docs/DOCUMENTATION.md

Setup

godot-mcp is two parts:

Part	Where it lives	What it does
Godot plugin	addons/godot_mcp_personal/ inside each Godot project	WebSocket server in the editor
Node MCP server	One clone of this repo anywhere on disk	Talks to Cursor over stdio, forwards to Godot

Copying only the addon into a project is not enough — Cursor must run the built Node server from a separate clone.

1. Clone and build the Node server (once)

git clone https://github.com/youssof20/godot-mcp.git
cd godot-mcp
npm install
npm run build

Confirm this file exists (use your real path):

Test-Path C:\dev\godot-mcp\dist\index.js   # should be True (use your clone path)

2. Add the plugin to your Godot project

Copy addons/godot_mcp_personal/ into your game's addons/ folder (or symlink it).

In Godot: Project → Plugins → Godot MCP → Enable

Confirm in the Output panel:

[godot-mcp] WebSocket server listening on ws://127.0.0.1:6505

3. Configure Cursor MCP (not inside the Godot project)

Edit Cursor Settings → MCP or your project's .cursor/mcp.json.

Replace the path below with the absolute path to dist/index.js from step 1 — not a placeholder, not a path inside your game project:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "node",
      "args": ["C:/dev/godot-mcp/dist/index.js"],
      "env": {
        "GODOT_MCP_PORT": "6505",
        "GODOT_MCP_MODE": "full"
      }
    }
  }
}

Use forward slashes or escaped backslashes on Windows. The path must point at the repo where you ran npm run build.

Restart the MCP server in Cursor after saving.

Troubleshooting

Error	Fix
Cannot find module ... dist/index.js	Wrong path in mcp.json — use absolute path to built repo; run npm run build
GODOT_NOT_CONNECTED	Godot not open, or plugin disabled, or wrong port
Stale tool count	Reload Godot project, npm run build, restart MCP server

After updates: reload Godot → npm run build → restart MCP server.

Verify

npm run test:tools    # 172 tools
npm run test:phase11

Docs

Doc	Purpose
DOCUMENTATION.md	Full project documentation
TOOL_MATRIX.md	All tools and status
PROTOCOL.md	WebSocket wire format
TESTING.md	Smoke tests

Env vars

Variable	Default
GODOT_MCP_PORT	6505
GODOT_MCP_MODE	full (minimal / lite / full)
ALLOW_GODOT_MCP_DANGEROUS	off

Status

Phases 0–11 complete. See DOCUMENTATION.md — Roadmap for optional next work.

MIT