FreightPX Godot MCP
Pixel-Freight/freightpx-godot-mcp
Bridge IA + Godot Engine para desenvolvimento de jogos assistido por agentes
Ver no GitHubServidor MCP que integra Claude e assistentes de IA diretamente com a Godot Engine, permitindo que agentes lancem o editor, executem projetos, capturem debug output e gerem código GDScript automaticamente. Cria um loop de feedback direto entre IA e engine para desenvolvimento de jogos mais eficiente.
Instalação
npx convez-ai Pixel-Freight/freightpx-godot-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar e testar código GDScript automaticamente com feedback em tempo real
- Depurar projetos Godot através de agentes IA que executam e analisam saída
- Criar cenas, gerenciar assets e exportar recursos (MeshLibrary) via IA
- Scaffolding de estrutura de projeto e boilerplate repetitivo
Veredito

Ferramenta especializada e bem arquitetada para quem quer IA gerando e testando código Godot com feedback real. Reduz significativamente o ciclo de desenvolvimento, mas exige familiaridade com MCP, TypeScript e Godot.
README
A tradução para o português deste README ainda está na fila.
FREIGHTPX GODOT MCP
_____ _____ ______ _____ _____ _ _ _______ _____ __ __
| ___| | __ \ | ____||_ _|| ____|| | | ||__ __|| __ \ \ \ / /
| |__ | |__) || |__ | | | |__ | |__| | | | | |__) | \ V /
| __| | _ / | __| | | | __| | __ | | | | ___/ > <
| | | | \ \ | |____ _| |_ | |____| | | | | | | | / . \
|_| |_| \_\|______||_____||______|_| |_| |_| |_| /_/ \_\
G O D O T M C P S E R V E R
A Model Context Protocol (MCP) server designed to supercharge your AI workflows by integrating seamlessly with the Godot Game Engine.
🚀 Introduction
FreightPX Godot MCP bridges the gap between AI agents and the Godot Game Engine. It enables agents to directly launch the Godot editor, execute run projects, capture debug output, and exert programmatic control over project execution. This direct feedback loop significantly enhances an AI's ability to generate accurate, context-aware Godot code and assist with complex debugging.
🤖 What This MCP Can Do
This MCP server acts as an intelligent bridge between your AI assistant (like Claude or Cursor) and the Godot Game Engine. It empowers the AI to perform the following actions entirely on its own:
- Launch & Run: Automatically open the Godot Editor or launch the game in debug mode.
- Inspect: List Godot projects, read project structures, and check installed Godot versions.
- Generate Code: Scaffold clean GDScript boilerplate to skip mundane typing.
- Edit Scenes: Create new
.tscnscene files, attach scripts to nodes, and inject new nodes into existing scenes. - Manage Assets: Load textures into Sprite nodes, resave resources, and retrieve UIDs for Godot 4.4+ projects.
- Export: Export 3D scenes as
MeshLibraryresources for GridMaps.
By using these tools, the AI can actively build, test, and debug your Godot game instead of just writing code snippets for you to copy and paste.
✨ Features
- Launch Godot Editor: Instantly open the Godot editor for a target project.
- Run & Debug Projects: Execute Godot projects in debug mode and capture console output and error messages in real-time.
- Project Inspection:
- Retrieve installed Godot versions.
- List available Godot projects within a specified directory.
- Analyze and extract detailed structural metadata about any project.
- Advanced Scene Management:
- Create new
.tscnscenes with specific root node types. - Programmatically add and configure nodes to existing scenes.
- Easily load sprites and textures into
Sprite2Dnodes. - Export 3D scenes as
MeshLibraryresources (GridMap support).
- Create new
- UID Management (Godot 4.4+):
- Retrieve the Unique ID (UID) for specific resources.
- Update and resave resource files to refresh UID references automatically.
🛠 Requirements
- Godot Engine installed on your system (Available at godotengine.org).
- Node.js (
>=18.0.0) andnpm. - An MCP-compatible AI Agent (e.g., Claude Desktop, Cline, Cursor).
⚡ Quick Start
Setting up the server is easy. Just configure your favorite AI agent to run the MCP server executable.
Claude Desktop / Claude Code
claude mcp add godot -- npx freightpx-godot-mcp
Note: Restart Claude Code after adding the server to initialize the Godot tools.
If your Godot executable isn't in your system PATH, supply it via environment variables:
claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx freightpx-godot-mcp
Add the following to your Cline MCP settings file (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["freightpx-godot-mcp"],
"env": {
"DEBUG": "true"
},
"disabled": false,
"autoApprove": [
"launch_editor", "run_project", "get_debug_output", "stop_project",
"get_godot_version", "list_projects", "get_project_info", "create_scene",
"add_node", "load_sprite", "export_mesh_library", "save_scene",
"get_uid", "update_project_uids"
]
}
}
}
⚙️ Environment Variables
| Variable | Description |
|---|---|
GODOT_PATH | Explicit path to your Godot executable (overrides the server's automatic detection). |
DEBUG | Set to "true" to enable detailed server-side debug logging. |
🏗 Architecture
The FreightPX Godot MCP server operates using a hybrid approach for maximum flexibility and performance:
- Direct Commands: Standard Godot CLI commands handle straightforward operations like launching the editor or retrieving project metadata.
- Bundled GDScript Operations: For complex, stateful tasks (e.g., scene modification, node injection), the server interfaces with a bundled GDScript (
godot_operations.gd). This script accepts JSON-formatted parameters via command-line arguments, executing the operation headless without needing to generate temporary scripts for every task.
🤝 Troubleshooting
- Godot Not Found: Set the
GODOT_PATHenvironment variable to your Godot executable path. - Connection Issues: Ensure the server is running and restart your AI assistant.
- Invalid Project Path: Ensure the path points to a directory containing a
project.godotfile. - Build Issues: Make sure all dependencies are installed by running
npm install.
📄 License
This project is licensed under the MIT License - see the LICENSE file for complete details.