Skip to main content
Glama

minimal-godot-mcp

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

npm License: MIT Node.js

Table of Contents

Related MCP server: Gear

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@latest"]
    }
  }
}

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

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

Configure your client to run:

npx -y @ryanmazzolini/minimal-godot-mcp@latest

All optional — defaults work for most setups.

Variable

Description

Default

GODOT_LSP_PORT

Override LSP port

6005

GODOT_WORKSPACE_PATH

Godot project path

Auto-detected from cwd

GODOT_DAP_PORT

Override DAP port

Tries 6006, 6010

GODOT_DAP_BUFFER_SIZE

Max console entries to buffer

1000

GODOT_DAP_CONNECT

lazy connects to DAP on the first get_console_output call instead of at startup. Frees one of Godot's 8 debug adapter slots per idle server, but output from before that call is lost

eager

Pass these as env in your MCP client config:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@ryanmazzolini/minimal-godot-mcp@latest"],
      "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. The server connects to Godot's debug adapter at startup and keeps the connection across runs, so output is captured from the moment a scene starts (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 (printerr() and runtime errors).

Runtime errors (for example calling a method on a null value) are reported by Godot as a debugger stop, not as output. They appear as stderr entries with the file and line of the failing frame. push_error() and push_warning() are not sent over DAP by Godot and cannot be captured.

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 :6005| Godot[Godot Editor]
    Server <-.->|DAP :6006| Godot
  • LSP (Language Server Protocol, solid line): Always connected for diagnostics

  • DAP (Debug Adapter Protocol, dotted line): Connects at startup and retries every 5 seconds while Godot is not reachable (set GODOT_DAP_CONNECT=lazy to connect on the first get_console_output call instead)

See also:

Building from Source

Prerequisites: npm 12.0.1 with a supported Node.js release (^22.22.2, ^24.15.0, or >=26)

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

License

MIT - see LICENSE

Available Tools

4 tools
clear_console_outputA

Clear the console output buffer. Use to reset output collection before running a specific test or action.

Inputs: no named parameters.

get_console_outputA

Get console output from Godot debug session. Returns print() statements, errors, and warnings captured during scene execution. Requires an active debug session (run a scene with F5 in Godot). Use to debug runtime behavior, check print output, or monitor warnings.

Inputs: limit, since, category.

get_diagnosticsA

Check GDScript files for errors after editing or when analyzing code. Returns syntax errors, type errors, undefined variables, missing functions, and code quality issues from Godot LSP (<1s). Use this tool when: user references .gd files, requests GDScript modifications, or reports code errors. For workspace-wide validation, use scan_workspace_diagnostics instead.

Inputs: file_path (required).

scan_workspace_diagnosticsA

Scan entire workspace for GDScript errors across all .gd files (~1-2s for 100+ files). Returns errors from all .gd files excluding addons/ and .godot/. Use to find all errors/warnings in the project. For single-file checks, use get_diagnostics instead (<1s).

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct scope: single-file diagnostics, workspace-wide diagnostics, console retrieval, and console clearing. The two diagnostics tools are explicitly differentiated by their descriptions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: get_diagnostics, scan_workspace_diagnostics, get_console_output, clear_console_output. The naming convention is uniform and predictable.

    Tool Count5/5

    Four tools is a well-scoped size for a minimal Godot-focused server. Each tool serves a necessary function without redundant bloat.

    Completeness4/5

    The diagnostics side is complete with both single-file and workspace coverage, and the console side covers retrieval and clearing. The only minor gap is that starting a debug session is not provided, so console output depends on an external action in the Godot editor.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers