The Minimal Godot MCP server bridges Godot's native Language Server Protocol (LSP) and Debug Adapter Protocol (DAP) to AI coding assistants for GDScript validation and debugging.
Check individual GDScript files for syntax errors, type errors, and code quality issues using
get_diagnostics(fast, <1s)Scan entire Godot projects for problems across all
.gdfiles withscan_workspace_diagnostics(excludesaddons/and.godot/directories; slower, 5-30s for 100+ files)Get real-time console output from running Godot scenes including print statements, stdout, and stderr messages via
get_console_output, with options to filter by category, time range, or limit entriesClear console buffer to manage memory and focus on new output using
clear_console_outputAuto-detect Godot workspace and connect to LSP/DAP ports without manual configuration, or use environment variables for custom setups
Handle Godot editor restarts automatically with resilient connection management
Minimize token usage with lightweight, focused responses optimized for AI coding assistants
Zero-config integration works with Godot 3.2+ or 4.x without requiring additional plugins
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 "Install 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 MCPcheck 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
Quick Start
Prerequisites: Node.js 22+, Godot 3.2+ or 4.x with LSP enabled
git clone https://github.com/ryanmazzolini/minimal-godot-mcp.git
cd minimal-godot-mcp
npm install && npm run buildStart Godot with your project, then configure your MCP client (see below).
Configuration
Environment Variables
Variable | Description | Default |
| Override LSP port | Tries 6007, 6005, 6008 |
| Godot project path | Auto-detected from cwd |
| Override DAP port | Tries 6006, 6010 |
| Max console entries to buffer |
|
MCP Client Setup
Add to ~/.claude.json:
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/path/to/minimal-godot-mcp/dist/index.js"],
"env": {
"GODOT_WORKSPACE_PATH": "/path/to/your/godot/project"
}
}
}
}Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/path/to/minimal-godot-mcp/dist/index.js"],
"env": {
"GODOT_WORKSPACE_PATH": "/path/to/your/godot/project"
}
}
}
}Configure your client to run:
node /path/to/minimal-godot-mcp/dist/index.jsSet GODOT_WORKSPACE_PATH environment variable to your Godot project root.
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. 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| GodotLSP (Language Server Protocol, solid line): Always connected for diagnostics
DAP (Debug Adapter Protocol, dotted line): Lazy-connects when
get_console_outputis called with a running scene
See also:
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.
References
Model Context Protocol - Protocol specification
Godot LSP - Language Server setup
ee0pdt/Godot-MCP - Full project control via custom plugin
Coding-Solo/godot-mcp - CLI-based GDScript operations
License
MIT - see LICENSE