Minimal Godot MCP
This server validates GDScript using Godot's native LSP and captures runtime console output via DAP, with no addon required.
Check a single GDScript file for errors (
get_diagnostics), returning syntax errors, type errors, undefined variables, missing functions, and code-quality warnings in under a second.Scan the whole workspace for GDScript errors (
scan_workspace_diagnostics), validating all.gdfiles (excludingaddons/and.godot/) in ~1–2s for 100+ files.Read console output from a running Godot debug session (
get_console_output), includingprint()statements, stdout, and stderr/runtime errors, with optionallimit,sincetimestamp, andcategoryfilters.Clear the console output buffer (
clear_console_output) to reset collection before running a specific test or action.
It connects automatically to Godot's LSP (port 6005) and DAP (6006/6010), survives Godot restarts, and pairs well with addon-based servers like godot-mcp for runtime control.
Uses ESLint for code linting during development of the MCP server
Built with Node.js runtime for executing the MCP server implementation
Distributed as an npm package for easy installation and dependency management
Uses Prettier for code formatting during development of the MCP server
Uses Shields.io badges to display package version and license information in documentation
Implemented in TypeScript for type-safe development of the MCP server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Minimal Godot MCP check this GDScript for syntax errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
minimal-godot-mcp
MCP server bridging Godot's native LSP to AI coding assistants for GDScript validation
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@latestAll optional — defaults work for most setups.
Variable | Description | Default |
| Override LSP port | 6005 |
| Godot project path | Auto-detected from cwd |
| Override DAP port | Tries 6006, 6010 |
| Max console entries to buffer |
|
|
|
|
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
.gdfiles 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| GodotLSP (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=lazyto connect on the firstget_console_outputcall 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 buildThen 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 TypeScriptContributing
Run
npm run format && npm testbefore submittingTest with a real Godot project
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
Available Tools
4 toolsclear_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
Scored across 4 tools
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.
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.
Four tools is a well-scoped size for a minimal Godot-focused server. Each tool serves a necessary function without redundant bloat.
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
Related MCP Connectors
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
MCP server for AI dialogue using various LLM models via AceDataCloud
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server providing 15 semantic analysis tools for GDScript, powered by Godot's built-in Language Server.4992 PyPI10Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to directly run, inspect, modify, and debug Godot game development projects through 110+ tools covering scenes, scripts, resources, runtime debugging, and asset management.333MIT
- AlicenseBqualityDmaintenanceAdvanced MCP server for Godot 4.6+ with 63 professional tools, enabling AI-assisted game development with backup/rollback, deep script validation, and project health diagnostics.635MIT
- AlicenseAqualityFmaintenanceA Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation via stdio and optional WebSocket bridge.389MIT