Godot MCP Server: Editing, Debugging, Scene Management

Overview

Godot MCP Server implements a small, language-agnostic protocol server that lets external tools manipulate Godot projects: edit scenes and resources, drive debugging sessions, and perform project-wide scene management tasks. The server exposes a structured JSON/JSON-RPC-style interface over a socket or TCP port so editors, CI scripts, and automation tools can operate on Godot projects without opening the full editor UI.

This is useful when you want to integrate Godot with other developer tools (IDEs, editor extensions, continuous validation scripts) or provide remote-control features for headless automation. Typical scenarios include programmatic scene refactors, remote debugging sessions, batch resource updates, or lightweight editing from an external IDE.

Features

• Remote scene and resource editing (open, modify, save)
• Debugging controls (start/stop debug sessions, set/clear breakpoints, step)
• Project-wide scene discovery and batch operations
• File watching and live-reload support for connected clients
• JSON/JSON-RPC protocol over TCP or Unix socket for easy integration
• Authentication token support for multi-user environments
• CLI for common tasks and example client scripts for automation
• Cross-project management: work with multiple Godot projects from one MCP instance

Installation / Configuration

The server is distributed as source in the Git repository. Example steps to get started from the repo:

Clone the repository

git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp

Build / install (example patterns)

# If the project provides a Python package
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m mcp_server

# If the project produces a binary (example)
# make build
# ./bin/mcp-server --config ./mcp.toml

Example minimal config (mcp.toml or mcp.json)

# mcp.toml
listen = "127.0.0.1:4567"          # TCP listen address or unix socket path
auth_token = "change-me"           # simple token-based auth
projects = ["./my_godot_project"]  # paths to managed Godot projects
log_level = "info"

Run the server with the chosen config:

mcp-server --config ./mcp.toml
# or
python -m mcp_server --config ./mcp.toml

Clients connect using the configured transport (TCP or Unix domain socket) and speak the protocol (JSON-RPC-like messages). For automation scripts, pass an Authorization header or initial handshake with the auth token.

Available Resources

• Repository: https://github.com/Coding-Solo/godot-mcp
• Example clients: CLI script, simple Node/Python client examples (see examples/ directory)
• Protocol docs: JSON message shapes for calls such as open_scene, edit_node, set_breakpoint, debug_start (refer to protocol.md in repo)
• Godot helper: small Godot editor plugin (optional) to accept connections and apply changes inside the editor
• Troubleshooting: logs are written to stdout and a rotating log file; increase log_level to debug for protocol traces

Resource table

Use Cases

1. Live editing from an external IDE

   • Use a lightweight editor (VS Code, Sublime) plus an MCP client to open and edit scene files without launching Godot. Edits are validated and pushed back to the project via the MCP server.

2. Batch scene refactor across projects

   • Run a script that connects to MCP, enumerates scenes, performs structured node renames or property updates, and saves scenes. Useful for large refactors (renaming a node type or changing export property names).

3. Automated scene validation in CI

   • In a CI job, start the MCP server in headless mode, run a validation script that checks scenes for missing scripts/resources or broken references, and fail the build if issues are found.

4. Remote debugging and instrumentation

   • Start a debugging session via MCP, set breakpoints programmatically, and collect variable dumps or call stacks. This enables remote diagnostics for test runs or servers running headless Godot builds.

5. Collaborative workflows and tooling

   • Integrate the MCP server into tooling that allows multiple team members to examine and propose scene edits, or to drive scripted demonstrations