minimal-godot-mcp

MCP server bridging Godot's native LSP to AI coding assistants for GDScript validation

Table of Contents

• Quick Start
• Configuration
• Features
• MCP Tools
• Development
• Troubleshooting
• Works Well With
• References
• License

Quick Start

Prerequisites: Node.js 22+, Godot 3.2+ or 4.x with LSP enabled

Configure your MCP client to run the server with npx (see examples below). Start Godot with your project open, and your MCP client will connect automatically.

Configuration

MCP Client Setup

Add to ~/.claude.json:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@ryanmazzolini/minimal-godot-mcp"]
    }
  }
}

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@ryanmazzolini/minimal-godot-mcp"]
    }
  }
}

Configure your client to run:

npx -y @ryanmazzolini/minimal-godot-mcp

All optional — defaults work for most setups.

Pass these as env in your MCP client config:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@ryanmazzolini/minimal-godot-mcp"],
      "env": {
        "GODOT_WORKSPACE_PATH": "/path/to/your/godot/project"
      }
    }
  }
}

Features

• Zero-config LSP - Uses Godot's native Language Server, no plugins required
• Fast diagnostics - Single-file checks return quickly
• Minimal footprint - Lightweight responses to minimize token usage
• Resilient connections - Handles Godot restarts automatically
• Workspace scanning - Bulk check all .gd files in a project

MCP Tools

get_diagnostics

Check a single GDScript file for errors.

// Input
{ "file_path": "/path/to/script.gd" }

// Output
{
  "diagnostics": {
    "/path/to/script.gd": [
      { "line": 5, "column": 14, "severity": "error", "message": "Expected identifier", "code": "parse-error" }
    ]
  }
}

scan_workspace_diagnostics

Scan all .gd files in the workspace (excludes addons/ and .godot/).

// Input
{}

// Output
{
  "files_scanned": 150,
  "files_with_issues": 3,
  "scan_time_seconds": 1.5,
  "diagnostics": { ... }
}

get_console_output

Get console output from Godot debug session. Requires a running scene (F5 in Godot).

// Input (all optional)
{
  "limit": 50,
  "category": "console",
  "since": 1706000000000
}

// Output
{
  "entries": [
    { "timestamp": 1706000001234, "category": "console", "message": "Player spawned", "source": "/project/player.gd", "line": 42 }
  ],
  "total_buffered": 150
}

Categories: console (print statements), stdout, stderr (errors/warnings).

clear_console_output

Clear the console output buffer.

// Input
{}

// Output
{ "cleared": true }

Development

Architecture

flowchart LR
    MCP[MCP Client] <-->|stdio| Server[minimal-godot-mcp]
    Server <-->|LSP :6007| Godot[Godot Editor]
    Server <-.->|DAP :6006| Godot

• LSP (Language Server Protocol, solid line): Always connected for diagnostics
• DAP (Debug Adapter Protocol, dotted line): Lazy-connects when get_console_output is called with a running scene

See also:

• Godot external editor setup

Building from Source

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

Then use node /path/to/minimal-godot-mcp/dist/index.js instead of npx in your MCP client config.

Commands

npm test          # Run tests
npm run lint      # ESLint + Prettier
npm run build     # Compile TypeScript

Contributing

1. Run npm run format && npm test before submitting
2. Test with a real Godot project
3. Keep scope focused on diagnostics

Troubleshooting

See docs/troubleshooting.md for connection issues, missing diagnostics, and debug logging.

Works Well With

godot-mcp by @satelliteoflove provides runtime control, scene manipulation, screenshots, stack traces, and direct editor interaction through a Godot addon. This project handles the LSP and DAP side — diagnostics and console output with no addon needed.

The two servers are complementary and can run side by side.

References

• Model Context Protocol - Protocol specification
• Godot LSP - Language Server setup

License

MIT - see LICENSE