AutoGodot

Autonomous game development framework that lets AI agents program, design scenes, and run visual QA on Godot 4.7 projects — all through the Model Context Protocol (MCP).

What It Does

An AI agent (Claude Desktop, VS Code, or any MCP-compatible client) can:

• Write game files — Create/edit GDScript (.gd) and scene (.tscn) files directly
• Run Godot tests — Launch the project, capture console output, detect errors
• Capture screenshots — Take visual QA screenshots of the running game for design verification

Quick Start (Ubuntu)

git clone https://github.com/YOUR_USERNAME/autogodot.git
cd autogodot
chmod +x scripts/setup_and_run.sh
./scripts/setup_and_run.sh

The setup script handles everything:

1. Verifies Python 3.10+ and Godot 4.7 are installed
2. Creates an isolated virtual environment
3. Installs all dependencies
4. Injects MCP server config into Claude Desktop (auto-detected)
5. Starts the MCP server

Manual Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python core/mcp_server.py

MCP Tools

Tool	Description
write_game_file	Create or overwrite .gd, .tscn, .tres files in the project
run_godot_test	Launch Godot with a scene, capture stdout/stderr, enforce timeout
capture_game_screen	Screenshot the running game window, return Base64 JPEG
read_scene	Parse a .tscn into structured JSON
create_scene	Build a .tscn from a JSON definition
modify_scene	Apply surgical operations to an existing .tscn

Configuration

Environment Variable	Default	Description
GODOT_PATH	godot4	Path to Godot 4.7 executable
GODOT_PROJECT	. (cwd)	Path to the Godot project directory
SKIP_CLAUDE_CFG	0	Set to 1 to skip Claude Desktop config injection

Project Structure

autogodot/
├── config/                  # MCP client config templates
├── core/
│   ├── __init__.py
│   ├── mcp_server.py        # MCP server (stdio transport)
│   ├── godot_controller.py  # Godot subprocess management
│   ├── scene_builder.py      # Structured .tscn manipulation (read/create/modify)
│   └── vision_qa.py          # Screen capture and visual QA
├── scripts/
│   └── setup_and_run.sh     # One-click Ubuntu setup
├── .gitignore
├── requirements.txt
└── README.md

Requirements

• Python 3.10 or later
• Godot 4.7 (recommended)
• OS Linux (Ubuntu 22.04+ recommended)

License

MIT