ryanmazzolini/minimal-godot-mcp

minimal-godot-mcp

Lightweight MCP server bridging Godot LSP to MCP clients for GDScript validation

Built with one mission: surface Godot diagnostics with minimal overhead.

Get instant GDScript syntax feedback in Claude, Cursor, and other MCP clients—no context switching to Godot, no custom plugins. Just a lightweight bridge to Godot's native LSP.

Table of Contents

• Quick Start
• Features
• Configuration
• Usage
• Comparison
• Development
• Contributing
• Troubleshooting
• Related Projects
• License

Quick Start

Prerequisites

• Node.js 24+
• Godot 3.2+ or 4.x with LSP enabled

Setup

Note: Package not yet published to npm. For now, clone and build locally.

# Clone and build
git clone https://github.com/ryanmazzolini/minimal-godot-mcp.git
cd minimal-godot-mcp
npm install
npm run build

# Start Godot editor with your project

Configure your MCP client (eg. Claude Code) to use the local build:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/minimal-godot-mcp/dist/index.js"]
    }
  }
}

Tip: See Configuration for environment variables and client-specific examples.

Restart your MCP client and start editing .gd files ✨

Features

• 🔌 Zero-config LSP integration - Uses Godot's native Language Server (no plugins, no extra dependencies)
• ⚡ Fast diagnostics - Single-file checks return in <1s
• 📦 Minimal footprint - <10MB memory, <200 LOC core implementation
• 💬 Low context overhead - Lightweight responses to minimize AI token usage
• 🔄 Resilient connections - Handles Godot restarts and reconnections automatically
• 🤝 Plays nice - Compatible with godot-vscode-plugin and other LSP clients
• 🌐 Workspace scanning - Optional bulk checking of all .gd files

See the context usage in Claude Code:

Configuration

Environment Variables

Set these environment variables in your MCP client configuration to customize behavior:

• GODOT_LSP_PORT: Override default port selection Default: tries ports 6007, 6005, 6008 in order Example: "GODOT_LSP_PORT": "6005"

• GODOT_WORKSPACE_PATH: Set Godot project path for LSP initialization Default: uses workspace from Godot's notification Example: "GODOT_WORKSPACE_PATH": "/absolute/path/to/your/godot/project"

MCP Client Examples

Claude Code (~/.claude/config.json):

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/minimal-godot-mcp/dist/index.js"],
      "env": {
        "GODOT_LSP_PORT": "6007",
        "GODOT_WORKSPACE_PATH": "/absolute/path/to/your/godot/project"
      }
    }
  }
}

Usage

1. Start Godot editor with your project
2. Verify LSP is running: nc -zv localhost 6007
3. Edit GDScript files with your MCP client enabled
4. Receive instant syntax error feedback

MCP Tools

get_diagnostics

Fast single-file diagnostic check (<1s).

Input:

{
  "file_path": "/absolute/path/to/script.gd"
}

Output:

{
  "diagnostics": {
    "/path/to/file1.gd": [
      {
        "line": 42,
        "column": 10,
        "severity": "error",
        "message": "Expected identifier after '.'",
        "code": "GD0001"
      }
    ]
  }
}

scan_workspace_diagnostics

⚠️ EXPENSIVE operation - scans ALL .gd files in workspace (5-30s for 100+ files).

Use sparingly for workspace-wide error checking. Requires GODOT_WORKSPACE_PATH environment variable.

Input:

{}

Output:

{
  "files_scanned": 150,
  "files_with_issues": 3,
  "scan_time_seconds": 12.45,
  "diagnostics": {
    "/path/to/file1.gd": [...],
    "/path/to/file2.gd": [...]
  }
}

Example in practice:

When you edit a GDScript file with a syntax error:

# player.gd
extends CharacterBody2D

func _ready():
    velocity. = Vector2(100, 0)  # Missing identifier after '.'

The MCP client receives:

{
  "diagnostics": {
    "/path/to/player.gd": [
      {
        "line": 5,
        "column": 14,
        "severity": "error",
        "message": "Expected identifier after '.'",
        "code": "parse-error"
      }
    ]
  }
}

Comparison

How minimal-godot-mcp differs from other Godot MCP servers:

Use minimal-godot-mcp when: You want lightweight syntax checking during AI-assisted GDScript editing

Use alternatives when: You need scene management, node creation, or full project control

Development

Architecture

┌─────────────┐         ┌────────────────────┐         ┌────────────┐
│ MCP Client  │ ◄─MCP─► │ minimal-godot-mcp  │ ◄─LSP─► │   Godot    │
│             │         │   (TypeScript)     │         │   Editor   │
└─────────────┘         └────────────────────┘         └────────────┘

LSP Communication:

1. Connect to Godot LSP via TCP (tries localhost ports 6007, 6005, 6008)
2. Send LSP initialize request
3. Sync documents with textDocument/didOpen
4. Receive textDocument/publishDiagnostics notifications
5. Cache and serve via MCP get_diagnostics tool

Testing

npm test          # Unit tests
npm run lint      # ESLint + Prettier

Manual testing:

1. Start Godot with test project
2. Run npm run dev
3. Configure MCP client
4. Introduce syntax error in .gd file
5. Verify diagnostic appears

Contributing

Contributions welcome! See Development for setup.

Before submitting:

• Run npm run format and npm test
• Verify changes work with a real Godot project
• Keep scope focused on diagnostics (no project manipulation)

Troubleshooting

"Connection refused on port 6007"

• Godot editor not running
• LSP disabled in project settings
• Firewall blocking localhost

"No diagnostics returned"

• File not part of Godot project
• File not opened in editor (LSP needs context)
• Syntax is actually valid

"Stale diagnostics"

• Cache not invalidating on file changes
• LSP not sending update notifications

Enable LSP Debug Logs

In Godot: Project → Project Settings → Network → Language Server → Log

Related Projects

• Model Context Protocol - The protocol specification
• Godot LSP Documentation - Godot's Language Server setup
• awesome-mcp-servers - Curated list of MCP servers
• godot-vscode-plugin - Official VSCode extension (uses same LSP)

Alternative Godot MCP servers:

• ee0pdt/Godot-MCP - Full project control via custom plugin
• Coding-Solo/godot-mcp - CLI-based GDScript operations

License

MIT License - see