Nexora Godot MCP

AI-native game development for Godot

A free, open-source and local-first MCP automation platform I designed to let AI systems work directly with Godot projects through structured, auditable and permission-aware operations.

Vision · Architecture · Security · Tool Catalog · Installer · AI Compatibility

Overview

I designed Nexora Godot MCP as a dedicated MCP server for Godot Engine. It is not an all-in-one MCP and it does not embed Nexora Forge or any other Nexora server.

Each MCP remains responsible for its own application:

AI / MCP Host
   │
   ├── Nexora Forge MCP  → Blender
   │
   └── Nexora Godot MCP  → Godot

The AI host decides which MCP to call based on the task. If a prompt is about modeling, the host can choose Forge. If it is about scenes, scripts, gameplay, UI, debugging or exporting a Godot game, it can choose Godot MCP.

My goal is to let an AI participate in real Godot development instead of only explaining what the developer should click or type.

Related MCP server: godot-mcp-server

Core principles

• Dedicated: Godot MCP controls Godot projects only.

• Local-first: the Godot editor and project remain on the user's machine.

• Self-hosted: users start and control their own MCP server.

• Provider-agnostic: the server does not depend on one AI vendor.

• Local-model friendly: any MCP-capable local AI host can use it.

• Structured first: normal work uses typed Godot operations instead of arbitrary shell or script execution.

• Human controlled: destructive or high-risk actions can require confirmation.

• Auditable: operations are logged without leaking secrets.

• Workspace confined: file operations remain inside approved project roots.

• Free and open source: no mandatory Nexora subscription or hosted account.

What it is designed to do

See docs/TOOL_CATALOG.md for the proposed MCP surface.

Current implementation

The Phase A foundation and Phase B scene/node production layer are implemented, establishing a real editor workflow rather than only documenting a future design.

Current MCP tools include:

• godot_status and nexora_capabilities;

• project inspection, validation and headless import;

• scene snapshot/open/save/create, open-scene state, reload and close;

• scene duplication, dependency inspection and PackedScene instancing;

• undoable node create/property/delete/rename/reparent operations;

• undoable Node2D and Node3D local/global transforms;

• scene owner repair for generated node subtrees;

• bounded Resource inspection;

• editor filesystem status, scan and asset reimport;

• GDScript/C# read/create/revision-aware replacement;

• managed project runs with explicit run_id, status, logs and stop;

• export preset discovery;

• debug, release and PCK/ZIP exports;

• bounded structured batch execution.

The Godot addon already provides a loopback-only bridge and a compact editor dock. The Python gateway keeps MCP/authentication logic outside the editor.

Quick start

Requirements:

• Python 3.11+

• uv

• Godot 4.6+ editor

• an existing Godot project

git clone https://github.com/Gh0stDeveloper/Nexora-Godot-MCP.git
cd Nexora-Godot-MCP
uv sync --all-extras

uv run nexora-godot setup --project /path/to/MyGame

Open or restart that project in Godot so the installed editor plugin starts its private bridge.

Then validate the installation:

uv run nexora-godot doctor

Start the MCP gateway:

uv run nexora-godot start

Default endpoints:

MCP:           http://127.0.0.1:8775/mcp
Health:        http://127.0.0.1:8775/health
Editor bridge: 127.0.0.1:9877

See docs/INSTALLER.md for the complete current setup flow.

Architecture

flowchart LR
    AI["AI / MCP Host"] -->|MCP| GW["Nexora Godot MCP Gateway"]
    GW -->|127.0.0.1 + bridge secret| PLUG["Godot Editor Plugin Bridge"]
    PLUG --> EDITOR["Godot Editor / Project"]
    GW --> CLI["Godot CLI Runner"]
    CLI --> RUN["Headless checks / run / export"]

The Python gateway owns authentication, permissions, path confinement, auditing and the public MCP tool surface.

The Godot editor plugin owns editor-only operations. It stays bound to 127.0.0.1 and processes structured requests on the editor thread.

The CLI runner handles operations Godot already exposes safely through its command line, such as import, parse/check, headless execution and export.

AI compatibility

Nexora Godot MCP does not contain a built-in dependency on GPT, Claude, Grok, DeepSeek or any local model.

Instead, it exposes an MCP server that any compatible host can call.

OpenAI API / ChatGPT-compatible host ─┐
Anthropic-compatible host            ├── MCP client → Nexora Godot MCP
Local AI host                        ┤
Custom agent framework               ┘

The model or host chooses the MCP; Nexora Godot MCP only performs validated Godot work.

Security model

The default profile allows structured project editing while blocking unrestricted operating-system commands and arbitrary code execution.

Important controls:

• editor bridge fixed to loopback;

• separate MCP and bridge secrets;

• project-root confinement;

• path normalization on both sides;

• confirmation for destructive operations;

• allowlisted Godot CLI commands;

• unrestricted script/shell execution disabled by default;

• sanitized JSONL audit log.

Target installation experience

nexora-godot setup
nexora-godot start
nexora-godot doctor

Planned lifecycle commands:

nexora-godot setup
nexora-godot start
nexora-godot stop
nexora-godot status
nexora-godot doctor
nexora-godot update
nexora-godot project add
nexora-godot project list
nexora-godot logs

Repository structure

.
├── apps/web/                       # optional local control center
├── godot_addon/
│   └── addons/nexora_godot_mcp/   # EditorPlugin + localhost bridge
├── src/nexora_godot_mcp/          # Python MCP gateway
├── scripts/                        # installer/start helpers
├── docs/                           # project documentation
├── examples/                       # MCP host examples
├── tests/                          # gateway/security/tool tests
└── .github/workflows/              # CI

Documentation

• Project vision

• Architecture

• Security

• Tool catalog

• Godot editor plugin

• Installer

• AI compatibility

• Local models

• Workflows

• Web design

• Roadmap

• Contributing

Credits & contact

Owner / Maintainer: Ghost Developer
Email: ghostnexora@gmail.com
Telegram: @Gh0stDeveloper

License

Nexora Godot MCP is released under the MIT License.

Nexora Godot MCP — AI-native game development for Godot.