Godot Agent MCP

A Godot MCP (Model Context Protocol) server that enables AI assistants like Claude, Cursor, and Zed to interact with Godot Engine through standardized tools and commands.

Overview

This plugin transforms your Godot editor into an MCP server, allowing AI coding assistants to:

• Create and manipulate scene nodes
• Inspect and modify project structure
• Execute Godot-specific operations remotely

The server implements the MCP specification and provides a robust foundation for building AI-assisted Godot development workflows.

Notably, the MCP runs in Godot, which reduces installation complexity and improves maintainability.

Features

• MCP-compliant HTTP server - Runs on localhost:8080
• Schema validation - Uses Zodot for type-safe parameter validation
• Extensible tool system - Easy to add new tools and capabilities
• JSON-RPC 2.0 support - Standard protocol implementation
• CORS protection - Restricted to localhost connections

Installation

Prerequisites

• Godot 4.x
• Git (for cloning the repository)

Setup

1. Clone the repository into your Godot project:

   cd your-godot-project
   git clone https://github.com/toasted-iron-studios/godot-agent-mcp.git
   # Or add as submodule
   git submodule add https://github.com/toasted-iron-studios/godot-agent-mcp.git addons/godot_agent_mcp
   

2. Enable the plugin:

   • Open your project in Godot
   • Go to Project → Project Settings → Plugins
   • Find "Godot Agent MCP" and enable it
   • The server will automatically start on port 8080

3. Verify installation:

   • Check the Output panel for "Godot Agent MCP plugin started"
   • The server should be accessible at http://127.0.0.1:8080

Usage

With AI Assistants

Configure your AI assistant to use the MCP server:

For Cursor/VSCode:

Copy-pasta the sample MCP config in the repo: mcp.json.sample

Available Tools

create_node

Creates a new node in the currently edited scene.

Parameters:

• parent_path (string): Path to the parent node (use "/root" for scene root)
• node_type (string): Godot node class name (e.g., "Node2D", "RigidBody3D")
• node_name (string): Name for the new node

Example:

{
  "parent_path": "/root",
  "node_type": "Node2D",
  "node_name": "Player"
}

Direct HTTP Usage

You can also interact with the server directly via HTTP:

curl -X POST http://127.0.0.1:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_node",
      "arguments": {
        "parent_path": "/root",
        "node_type": "Node2D", 
        "node_name": "MyNode"
      }
    },
    "id": 1
  }'

Architecture

Core Components

• plugin.gd - Main plugin entry point, manages server lifecycle
• HttpServer - HTTP server handling MCP requests
• MCPRouter - Routes MCP method calls to appropriate handlers
• MCPTool - Abstract base class for all tools
• Zodot - Schema validation library for type safety

Request Flow

AI Assistant → HTTP Request → HttpServer → MCPRouter → MCPTool → Godot API

1. AI assistant sends JSON-RPC 2.0 request
2. HttpServer validates and parses the request
3. MCPRouter routes to the appropriate tool
4. Tool validates parameters using Zodot schemas
5. Tool executes Godot operations and returns results

Tool Architecture

Tools inherit from MCPTool and implement:

• get_name() - Unique tool identifier
• get_description() - Human-readable description
• get_input_schema() - Zodot schema for parameter validation
• run(params) - Tool execution logic

Contributing

Code Quality Standards

We maintain strict code quality standards to ensure a professional, maintainable codebase:

NO INLINE COMMENTS

• NEVER use inline comments (single # comments within function bodies)
• Inline co

... View full README on GitHub