godot-lsp-stdio-bridge

A stdio-to-TCP bridge for Godot's GDScript Language Server. Enables AI coding agents to use Godot's LSP for code intelligence.

npm: https://www.npmjs.com/package/godot-lsp-stdio-bridge

Why?

Most AI coding tools (Claude Code, Cursor, OpenCode, etc.) expect LSP servers to communicate via stdio, but Godot's LSP only supports TCP (port 6005). This bridge solves that.

Features

Feature	Description
stdio ↔ TCP Bridge	Converts between stdio (AI tools) and TCP (Godot LSP)
Binary-Safe Buffers	Uses Buffer.concat() instead of string concatenation - fixes data loss with large files
Auto Port Discovery	Automatically tries ports 6005, 6007, 6008 if connection fails
Auto Reconnection	Reconnects automatically when Godot Editor restarts
Windows URI Normalization	Converts C:\path to /C:/path for cross-platform compatibility
Notification Buffering	Buffers notifications until initialize response (fixes Godot's non-standard ordering)
Memory Protection	10MB buffer limit and 1000 message queue limit to prevent memory exhaustion
Graceful Shutdown	Handles SIGINT, SIGTERM, SIGHUP signals properly
Zero Dependencies	Pure Node.js, no external dependencies

Requirements

• Node.js 18+
• Godot Editor running with your project open (LSP server runs on port 6005)

Installation

npm install -g godot-lsp-stdio-bridge

Or use directly with npx:

npx godot-lsp-stdio-bridge

Configuration

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "lsp": {
    "gdscript": {
      "command": ["npx", "godot-lsp-stdio-bridge"],
      "extensions": [".gd", ".gdshader"]
    }
  }
}

Claude Code

Add to your MCP settings or Claude configuration:

{
  "lsp": {
    "gdscript": {
      "command": ["npx", "godot-lsp-stdio-bridge"],
      "extensions": [".gd"]
    }
  }
}

Cursor

In Cursor settings, add a custom language server:

{
  "gdscript": {
    "command": ["npx", "godot-lsp-stdio-bridge"],
    "filetypes": ["gdscript"]
  }
}

VS Code / Generic LSP Client

{
  "languageserver": {
    "gdscript": {
      "command": "npx",
      "args": ["godot-lsp-stdio-bridge"],
      "filetypes": ["gdscript"],
      "rootPatterns": ["project.godot"]
    }
  }
}

Neovim (nvim-lspconfig)

local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

configs.gdscript_bridge = {
  default_config = {
    cmd = { 'npx', 'godot-lsp-stdio-bridge' },
    filetypes = { 'gdscript' },
    root_dir = lspconfig.util.root_pattern('project.godot'),
  },
}

lspconfig.gdscript_bridge.setup{}

Windows

On Windows, npm creates .cmd wrapper scripts for global packages:

{
  "lsp": {
    "gdscript": {
      "command": ["godot-lsp-stdio-bridge.cmd"],
      "extensions": [".gd"]
    }
  }
}

Environment Variables

Variable	Default	Description
GODOT_LSP_PORT	Auto-discover	Fixed port (skips auto-discovery if set)
GODOT_LSP_HOST	127.0.0.1	Godot LSP server host
GODOT_LSP_BRIDGE_DEBUG	false	Enable debug logging
GODOT_LSP_BRIDGE_LOG	/tmp/godot-lsp-stdio-bridge.log	Log file path (Windows: %TEMP%\godot-lsp-stdio-bridge.log)

Usage

1. Open Godot Editor with your project
2. Start your AI coding tool (it will automatically start the bridge)
3. Edit .gd files - you'll get diagnostics, symbols, go-to-definition, etc.

LSP Features

Once connected, you get full GDScript LSP features:

• Diagnostics (errors, warnings)
• Document symbols
• Go to definition
• Find references
• Hover information
• Completion suggestions
• Signature help

How it works

┌─────────────────┐     stdio      ┌─────────────────┐      TCP       ┌─────────────────┐
│   AI Coding     │ ─────────────► │  godot-lsp-     │ ─────────────► │   Godot LSP     │
│   Agent         │ ◄───────────── │  stdio-bridge   │ ◄───────────── │   Server        │
│ (Claude, etc.)  │                │                 │                │   (port 6005)   │
└─────────────────┘                └─────────────────┘                └─────────────────┘

Port Discovery

If GODOT_LSP_PORT is not set, the bridge tries these ports in order:

1. 6005 - Default Godot LSP port
2. 6007 - Alternative port (some Godot versions)
3. 6008 - Fallback port

Reconnection Flow

1. Connection lost → Wait 5 seconds
2. Try to reconnect (with port discovery)
3. On success → 1 second warmup delay → Flush buffered messages
4. Notify client: "Godot LSP server restarted"

Troubleshooting

"Connection failed" error

Make sure Godot Editor is running with your project open. The LSP server only runs when the editor is active.

Enable debug logging

GODOT_LSP_BRIDGE_DEBUG=true npx godot-lsp-stdio-bridge

Check logs at /tmp/godot-lsp-stdio-bridge.log (Linux/macOS) or %TEMP%\godot-lsp-stdio-bridge.log (Windows)

Custom port

If Godot uses a different port:

GODOT_LSP_PORT=6008 npx godot-lsp-stdio-bridge

Large file issues

This bridge uses binary-safe Buffer.concat() instead of string concatenation, which prevents data loss with large GDScript files (80KB+). If you experience issues with other bridges, this one should work.

Comparison with other bridges

Feature	godot-lsp-stdio-bridge (this)	opencode-godot-lsp	godot-lsp-bridge (can0pus)
Binary-safe buffers	✅ Buffer.concat()	❌ .toString()	❌ .toString()
Auto port discovery	✅ 6005, 6007, 6008	❌	✅
Auto reconnection	✅	❌	✅
Windows URI normalization	✅	❌	✅
Memory protection	✅ 10MB limit	❌	✅
Dependencies	None	None	None
Build required	❌	❌	✅ TypeScript

License

MIT

Contributing

Issues and PRs welcome at GitHub.

Acknowledgments

• Godot Engine - The open-source game engine that provides the GDScript Language Server
• Disunday - Control OpenCode from Discord

Sponsors

Redimo - The Ultimate Redis GUI Client. Visualize, Manage, and Monitor.