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:

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

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

Related MCP server: godot-forge

Verify

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

Docs

Env vars

Status

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

MIT