Minimal Godot

You can bridge Godot’s native Language Server Protocol (LSP) to AI coding assistants for GDScript validation with a lightweight MCP server. It enables fast single-file diagnostics, bulk workspace checks, and resilient connections during Godot restarts, all with a minimal footprint.

How to use

You run the MCP server through your MCP client using a common command, and Godot connects automatically when you start your project. Use the server to get immediate diagnostics for GDScript files, scan entire workspaces for issues, and fetch console output from a running Godot scene.

How to install

Prerequisites: Node.js 22 or later, and Godot 3.2 or newer with LSP support.

Install and run from the MCP client configuration using the stdio (local) command shown here.

# Clone the project (optional if you are using the MCP server via npx)
# git clone https://github.com/ryanmazzolini/minimal-godot-mcp.git
# cd minimal-godot-mcp

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Run the MCP server locally via the MCP client (example command)
# node dist/index.js

Configuration

Configure your MCP client to launch the server using a standard npx-based command. The following shows the supported local (stdio) configuration you can place in your MCP client settings to start the server.

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

MCP tools and endpoints

This server exposes a small set of endpoints to help you validate and inspect your GDScript projects. You can check individual files for syntax issues, scan an entire workspace for problems, and retrieve relevant console output from a running Godot scene.

Key capabilities include diagnosing a single file, scanning workspace diagnostics, getting console output, and clearing the console buffer.

Troubleshooting

If you encounter connection issues, verify that Godot is running with the project open and that your MCP client is configured to connect to the server. Check that the Node.js runtime is available and that the MCP server process can be started with the provided command. For missing diagnostics or unexpected errors, ensure Godot’s LSP is active and that the workspace path is correctly set if you use advanced environment configuration.

Notes

The MCP server uses Godot’s built-in LSP for diagnostics and exposes a DAP interface lazily for console access when a scene is running. The server is designed to be lightweight and to restart automatically if Godot restarts.

Available tools

get_diagnostics

Check a single GDScript file for syntax errors and issues, returning structured diagnostics keyed by the file path.

scan_workspace_diagnostics

Scan all .gd files in the workspace, excluding addons/ and .godot/, returning counts of scanned files, issues found, and total diagnostics.

get_console_output

Retrieve console output from a running Godot debug session, with optional limits and filters for category and since timestamp.

clear_console_output

Clear the current in-memory console output buffer.