Godot DAP MCP Server
Status: ๐ง Active Development - Phase 8 Complete โ | Documentation โณ
An MCP (Model Context Protocol) server that enables AI agents to perform interactive runtime debugging of Godot games via the Debug Adapter Protocol (DAP).
Current Capabilities
Phase 1-3: Core Debugging (Complete):
- โ Connect to Godot editor via DAP
- โ Set, verify, and clear breakpoints
- โ Control execution (continue, step over, step into)
- โ Session management
Phase 4: Runtime Inspection (Complete):
- โ Get stack traces with source locations
- โ Inspect variable scopes (Locals, Members, Globals)
- โ Browse complex objects (Arrays, Dictionaries, Nodes)
- โ Evaluate GDScript expressions at runtime
- โ Godot-specific type formatting (Vector2, Color, etc.)
Phase 5: Scene Launching (Complete):
- โ Launch main scene, specific scene, or current editor scene
- โ Configure debug options (profiling, collisions, navigation)
- โ Validates project paths
Phase 6-8: Advanced & Polish (Complete):
- โ
godot_pause: Pause running game - โ
godot_set_variable: Available but currently disabled due to upstream Godot limitation - โ Robust Error Handling: Problem/Context/Solution error messages
- โ
Path Resolution: Auto-converts
res://paths to absolute paths - โ Timeout Protection: Prevents hangs from unresponsive DAP server
- โ Event-Driven Architecture: Handles complex interleaved DAP events
Planned Features
- Upstream Improvements:
stepOutsupport (PR Submitted: godotengine/godot#112875)setVariablesupport (Planned PR)
- Documentation: Complete tool reference and examples
Architecture
MCP Client (Claude Code) โ stdio โ MCP Server โ TCP/DAP โ Godot Editor โ Game Instance
This server bridges Claude Code (or any MCP client) to Godot's built-in DAP server, enabling AI-assisted debugging workflows.
Architecture:
- MCP Layer (
internal/mcp/): stdio-based JSONRPC 2.0 communication - DAP Client (
internal/dap/): Event-driven TCP client for Godot's DAP server - Tool Layer (
internal/tools/): Godot-specific MCP tools with error handling & path resolution
Documentation
Comprehensive documentation is available in the docs/ directory:
- docs/PLAN.md - Project status and roadmap
- docs/TOOLS.md - Complete tool reference (Coming Soon)
- docs/EXAMPLES.md - Usage examples (Coming Soon)
- docs/ARCHITECTURE.md - System design
- docs/TESTING.md - Testing guide
Installation
For Testing/Development:
# Build from source
go build -o godot-dap-mcp-server cmd/godot-dap-mcp-server/main.go
# Run all tests
go test ./...
# Run integration tests (requires Godot 4.2.2+)
./scripts/automated-integration-test.sh
Quick Start
- Start Godot Editor with your project.
- Run MCP Server (via Claude Code or manually).
- Connect:
godot_connect(project="/path/to/your/project") - Set Breakpoint:
godot_set_breakpoint(file="res://player.gd", line=10) - Launch:
godot_launch_main_scene(project="/path/to/your/project") - Debug: Use
godot_step_over,godot_get_stack_trace,godot_evaluate, etc.
License
MIT License - see LICENSE