What can you do with this server?

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 .gd files with scan_workspace_diagnostics (excludes addons/ 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 entries * Clear console buffer to manage memory and focus on new output using clear_console_output * Auto-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

Which integrations are available for this server?

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

How do I use Minimal Godot MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

Q: Which integrations are available for this server?

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

Q: How do I use Minimal Godot MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

by ryanmazzolini

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

minimal-godot-mcp

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

npm License: MIT Node.js

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

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.

Variable	Description	Default
`GODOT_LSP_PORT`	Override LSP port	Tries 6007, 6005, 6008
`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`

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

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

Run npm run format && npm test before submitting
Test 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 tools

clear_console_outputA

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description accurately describes the destructive action but provides no additional behavioral context beyond the basic operation, such as irreversibility or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the core action and follow with usage guidance, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description fully covers its purpose and when to use it, leaving no gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the description has no parameter information to add, but schema coverage is 100%, so baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Clear the console output buffer') and the resource, distinguishing it from sibling tools like get_console_output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use before running a specific test or action, providing clear context for when to invoke this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of entries to return (most recent). Default: all buffered.
`category`	No	Filter by output category. console=print(), stdout=standard out, stderr=errors.
`since`	No	Unix timestamp (ms). Only return entries after this time.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes it as a read operation returning specific data types, and mentions a prerequisite. No annotations are present, so the description carries the burden and does so adequately without contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the main action and provide necessary context without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 optional parameters and no output schema, the description explains the return value and a prerequisite, covering most gaps. Could mention limits or default behavior but is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema, but the schema itself is clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'console output from Godot debug session', and distinguishes from sibling tools like clear_console_output and get_diagnostics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear use cases (debug runtime behavior, check print output, monitor warnings) and a prerequisite (active debug session), but does not explicitly mention when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes	Absolute path to the GDScript (.gd) file to analyze for errors, warnings, and issues.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It lists the types of issues returned and mentions execution time (<1s) and the use of Godot LSP. It does not explicitly state side effects (likely none), but it is clear that the operation is a diagnostic check.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no wasted words. It front-loads the purpose and output, then provides usage context and alternatives. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter diagnostic tool without an output schema, the description covers the purpose, return types (listing specific errors), usage conditions, and alternatives. No gaps are apparent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already describes the parameter. The description does not add any additional semantics about the file_path parameter beyond what the schema provides, meeting the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Check', the resource 'GDScript files', and the specific outputs (syntax errors, type errors, etc.). It also distinguishes from the sibling tool 'scan_workspace_diagnostics' by directing workspace-wide validation to that tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use this tool: when user references .gd files, requests modifications, or reports errors. Also explicitly states when not to use it and directs to the sibling tool for workspace-wide validation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It discloses scope, exclusions, and performance (~1-2s). While it implies a read operation, it does not explicitly state non-destructiveness, but context suggests it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with key information, no wasted words. Efficiently conveys purpose, scope, performance, and alternative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and simple operation, the description covers all needed context: what, where, when, performance, and alternative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description adds context about what is scanned and excluded, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it scans the entire workspace for GDScript errors across all .gd files, excluding addons/ and .godot/. It distinguishes from the sibling tool get_diagnostics for single-file checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit guidance: use for finding all errors/warnings in the project, and for single-file checks, use get_diagnostics instead. Also includes time estimates.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

2 tool updatesv1.0.1May 10, 2026
- Addedclear_console_output
- Addedget_console_output
2 tool updatesOct 13, 2025
- First observedget_diagnostics
- First observedscan_workspace_diagnostics

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored 2026-09-09 23:51 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

ActivityStale

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

Gessa: game asset generation for AI agentsOAuth
ai.gessa
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
AI & Machine Learning Image & Video Processing Audio Processing
1
mcp-aichatOAuth
io.github.AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
AI & Machine Learning
2
Svelte MCP A
dev.svelte
The official Svelte MCP server providing docs and autofixing tools for Svelte development
Developer Tools Documentation Access Code Analysis
42327
ChiR24-unreal_mcp_serverOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Developer Tools App Automation Software Architecture
2875

Related MCP Servers

godotlens-mcp
Developer Tools Code Analysis Command Line
pzalutski-pixel
A
license
A
quality
A
maintenance
An MCP server providing 15 semantic analysis tools for GDScript, powered by Godot's built-in Language Server.
Updated 2 months ago (2026-07-27 14:15 UTC)
33
26 PyPI
8
Apache 2.0
Gear
Developer Tools Code Execution App Automation
wvfp
A
license
A
quality
D
maintenance
An 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.
Updated 3 months ago (2026-06-15 13:26 UTC)
33
21 npm
2
MIT
Godot MCP Server Ultimate
Developer Tools Code Analysis Coding Agents
Dex865378
A
license
B
quality
D
maintenance
Advanced 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.
Updated 6 months ago (2026-04-04 18:49 UTC)
63
131 npm
5
MIT
godot-devtool
Developer Tools Testing & QA Tools
wangdiandao
A
license
A
quality
B
maintenance
A Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation via stdio and optional WebSocket bridge.
Updated 3 months ago (2026-06-29 02:39 UTC)
3
90
MIT

Appeared in Searches

Using Cursor, Claude, and Windsurf MCP with Godot Engine

minimal-godot-mcp

Table of Contents

Quick Start

Configuration

MCP Client Setup

Features

MCP Tools

get_diagnostics

scan_workspace_diagnostics

get_console_output

clear_console_output

Development

Architecture

Building from Source

Commands

Contributing

Troubleshooting

Works Well With

References

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches

`get_diagnostics`

`scan_workspace_diagnostics`

`get_console_output`

`clear_console_output`