RectangleEquals/godotmcp

GodotMCP

AI-Powered Godot 4.4+ Project Management via Model Context Protocol

GodotMCP is a Model Context Protocol (MCP) server that enables Claude and other AI assistants to manage Godot game projects through the GodotAI GDExtension. It provides comprehensive project management, file operations, git-based modification tracking, and debugging capabilities—all with user approval workflows.

🎯 Features

• 📁 Project Management: Get project info, file structure, and Godot settings
• 📝 File Operations: Read, create, modify, and delete files with git tracking
• 🔄 Git Integration: Full git workflow with diff viewing, approval/denial, undo/redo
• 🐛 Debugging Support: Run and debug Godot projects through VS Code integration
• 🔒 Permission System: Granular folder access control and auto-approval rules
• ✅ User Approval: Review and approve all AI-suggested changes before applying
• 📊 Change History: Track and navigate through all modifications

🏗️ Architecture

Claude Desktop ↔ Docker MCP Toolkit ↔ GodotMCP (Docker) ↔ GodotAI (GDExtension) ↔ Godot Project

• GodotMCP: Python MCP server running in Docker, proxying requests between Claude and GodotAI
• GodotAI: C++ GDExtension running in your Godot project, performing actual file and git operations
• Communication: Async HTTP/SSE between GodotMCP and GodotAI, stdio for Claude Desktop

📋 Prerequisites

• Windows 10/11 with WSL 2
• Docker Desktop with MCP Toolkit beta feature enabled
• Claude Desktop for Windows
• Godot 4.4+ with your game project
• Python 3.11+ (for development)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/RectangleEquals/godotmcp.git
cd godotmcp

2. Run the Installation Script

Open PowerShell and run:

.\install.ps1

This will:

• Copy MCP configuration files to Docker MCP directories
• Build the Docker image
• Register the server with Docker Desktop
• Optionally configure Claude Desktop

3. Install GodotAI GDExtension

(GodotAI setup instructions will be provided separately)

1. Download GodotAI from the releases page
2. Extract to res://addons/godotai/ in your Godot project
3. Configure res://addons/godotai/config.json
4. Enable the addon in Godot's Project Settings

4. Start Using in Claude Desktop

Open Claude Desktop and you can now use GodotMCP tools:

Can you show me the structure of my Godot project?

Create a new Player script at res://scripts/player.gd with basic movement code

Show me pending changes and let me approve them

🔧 Configuration

Environment Variables

GodotMCP supports the following environment variables:

You can set these in your Docker configuration or when building the image.

GodotAI Configuration

Configure GodotAI by editing res://addons/godotai/config.json:

{
  "listen_port": 9876,
  "permissions": {
    "allowed_folders": [
      "res://scripts/**",
      "res://scenes/**",
      "res://assets/**"
    ],
    "denied_folders": [
      "res://addons/godotai/**"
    ]
  },
  "auto_approve": {
    "patterns": [],
    "max_file_size_kb": 0
  },
  "auto_deny": {
    "patterns": [
      "**/*.import",
      ".godot/**"
    ]
  },
  "max_undo_history": 50,
  "enable_debug_mode": false
}

📚 Available Tools

Project Information

• get_project_info - Get project name, Godot version, and settings
• get_project_structure - Get complete file/folder structure
• get_git_status - Get current git status and history

File Operations

• read_file(path) - Read file contents
• list_files(directory) - List files in a directory
• search_files(pattern, directory) - Search for files matching a pattern

File Modifications (Git-Tracked)

• create_file(path, content, commit_message) - Create a new file
• modify_file(path, content, commit_message) - Modify existing file
• delete_file(path, commit_message) - Delete a file

Git Workflow

• get_pending_changes() - View changes awaiting approval
• approve_changes(change_ids) - Approve one or more changes
• deny_changes(change_ids) - Deny and revert changes
• retry_change(change_id) - Deny and ask Claude to retry
• undo_changes(count) - Undo recent changes
• redo_changes(count) - Redo undone changes
• get_change_history(limit) - View change history

Debugging & Execution

• run_project(scene) - Run the Godot project
• debug_project(scene, breakpoints) - Start debugging with VS Code
• stop_project() - Stop running/debugging project
• get_debug_logs(since, level) - Get debug logs

Configuration

• get_godotai_config() - Get GodotAI settings
• update_godotai_config(config) - Update GodotAI settings
• health_check() - Check GodotAI connection status

🔄 Workflow Example

Creating and Approving Changes

1. Ask Claude to create a file:

   Create a player controller script at res://scripts/player_controller.gd
   

2. Claude uses create_file tool - File is created and git-tracked

3. View pending changes:

   Show me what changes are pending approval
   

4. Review the diff - Claude shows you the git diff

5. Approve or deny:

   Approve all pending changes
   

   OR

   Deny the last change and let's try again with more detailed comments
   

6. Undo if needed:

   Actually, undo the last 2 changes
   

🏗️ Project Structure

godotmcp/
├── src/
│   └── godot_mcp_server/
│       ├── __init__.py          # Package init
│       └── server.py            # Main MCP server
├── .mcp/
│   └── catalog/
│       ├── custom-catalog.yaml  # MCP catalog config
│       └── v3/
│           └── tools/
│               └── godotmcp.json # Tool definitions
├── .claude/
│   └── claude_desktop_config.json # Claude Desktop config
├── Dockerfile                    # Docker container config
├── pyproject.toml               # Python project config
├── install.ps1                  # Windows installation script
├── README.md                    # This file
└── LICENSE                      # MIT License

🧪 Development

Building Locally

# Build Docker image
docker build -t godotmcp:latest .

# Run locally for testing
docker run -it --rm \
  -e GODOTAI_HOST=host.docker.internal \
  -e GODOTAI_PORT=9876 \
  godotmcp:latest

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/

# Type checking
mypy src/

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see file for details.

🔗 Related Projects

• GodotAI - The C++ GDExtension that GodotMCP communicates with (coming soon)
• calcmcp - The template MCP server this project is based on
• godot-plus-plus - Template for GDExtension projects

💬 Support

• Open an issue for bug reports or feature requests
• Check the Model Context Protocol documentation
• Join the discussion on GitHub Discussions

🙏 Acknowledgments

• Built on the Model Context Protocol
• Uses FastMCP for the server implementation
• Inspired by the need for better AI-assisted game development workflows

⚠️ Note: GodotMCP is currently in beta. The GodotAI GDExtension component is under active development.