o3de-mcp

Automate Open 3D Engine (O3DE) with AI — an MCP server for editor control, project & build management.

See the architecture documentation for a detailed system diagram and communication flow.

Features

Capability Detection:

• get_capabilities — check editor connectivity and CLI availability before using other tools

• Dynamic tool discovery — new tools are automatically reported

Editor Automation (requires a running O3DE Editor with the AiCompanion + EditorPythonBindings gems):

• Execute arbitrary Python scripts inside the editor (azlmbr API)

• List, create, delete, and duplicate entities

• Add components, get/set component properties

• Load, save, and query levels

• Enter/exit game mode, undo/redo

• Fast-fail when editor is unreachable (avoids repeated timeouts)

Project & Build Management (CLI-based, no editor required):

• Discover local O3DE engine installations (multi-engine support)

• List registered projects, gems, and available templates

• Create projects and gems from templates

• Register, enable, and disable gems

• Edit project properties

• Build projects via CMake

• Export projects for distribution

Related MCP server: mcp-bridge

Prerequisites

• Python 3.10+

• O3DE installed and registered (engine path in the O3DE manifest or O3DE_ENGINE_PATH env var)

  • Linux/macOS: ~/.o3de/o3de_manifest.json

  • Windows: %USERPROFILE%\.o3de\o3de_manifest.json

• For editor tools (optional): O3DE Editor running with the o3de-ai-companion-gem and EditorPythonBindings gems enabled. The companion gem provides the AgentServer that o3de-mcp connects to for real-time editor automation. Project tools work without the editor — call get_capabilities() to check what's available.

Installation

pip install -e .

Or with uv:

uv pip install -e .

Usage

As a standalone MCP server

o3de-mcp

With Claude Code

Add to your MCP config (or use a project-level .mcp.json):

• Linux/macOS: ~/.claude/mcp.json

• Windows: %USERPROFILE%\.claude\mcp.json

{
  "mcpServers": {
    "o3de": {
      "command": "o3de-mcp"
    }
  }
}

With Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "o3de": {
      "command": "o3de-mcp"
    }
  }
}

Testing with MCP Inspector

MCP Inspector provides a web UI for interactively testing tools without an AI assistant. Useful for verifying tool behavior, inspecting responses, and debugging.

npx @modelcontextprotocol/inspector o3de-mcp

This opens the Inspector UI at http://localhost:6274. From there you can browse all registered tools, invoke them with custom parameters, and see raw responses.

To pass environment variables (e.g., a custom engine path or editor port):

npx @modelcontextprotocol/inspector -e O3DE_ENGINE_PATH=/path/to/engine -e O3DE_EDITOR_PORT=4600 o3de-mcp

Development

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

# Run tests
pytest

# Run a single test
pytest tests/test_project.py::TestValidateName::test_valid_simple

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/

SBOM (Software Bill of Materials)

A CycloneDX SBOM is generated on every CI run and uploaded as a build artifact. To generate one locally:

python scripts/generate-sbom.py              # JSON + XML
python scripts/generate-sbom.py --format json # JSON only

The script creates an isolated virtual environment with only runtime dependencies, so the SBOM accurately reflects what ships — dev/build tooling is excluded.

CI

GitHub Actions runs lint, type checking, tests, and SBOM generation on every push and PR to main. See .github/workflows/ci.yml.

Security

• Editor tool inputs (entity IDs, component types) are validated against strict regex patterns before use.

• User-supplied strings are serialized via json.dumps / json.loads when passed into editor scripts — never raw string interpolation.

• Project and gem names are validated against O3DE naming conventions.

• Filesystem paths are resolved and validated before being passed to subprocesses.

Documentation

Examples

Progressive walkthroughs from project creation to a complete game:

1. New Project — create, configure, and build a project

2. Build a Scene — sky, lights, ground, camera, static objects

3. Physics Playground — dynamic bodies, triggers, stacking

4. Scripted Game — complete mini-game with player, obstacles, goals

5. Batch Operations — efficient bulk entity creation patterns

6. CLI-Only Workflow — project management without the editor

7. Gem Development — create and integrate custom gems

8. MCP Inspector — interactively test tools via a web UI

Configuration

Editor timeouts: the editor runs each submitted script synchronously and does not reply until it finishes, so O3DE_EDITOR_TIMEOUT is effectively "how long an editor operation may take." It defaults to 600s because real operations (level loads, game-mode entry, on-demand asset compilation) routinely exceed tens of seconds — a too-short value cuts them off while the editor is still working. An unreachable editor is caught in milliseconds by the separate O3DE_EDITOR_CONNECT_TIMEOUT and the fast-fail window, so a large command timeout costs nothing on the healthy path. run_editor_python also accepts a per-call timeout argument.

The server also reads the O3DE manifest for registered engines, projects, and gems:

• Linux/macOS: ~/.o3de/o3de_manifest.json

• Windows: %USERPROFILE%\.o3de\o3de_manifest.json

Related Projects

• o3de-ai-companion-gem — O3DE Gem that provides the AgentServer for editor-side communication. Required for editor automation tools. Enable it alongside EditorPythonBindings in your O3DE project.

• O3DE (Open 3D Engine) — The open-source game engine.

License

This project is dual-licensed under Apache 2.0 or MIT (your choice), matching the O3DE engine license. Free for commercial and non-commercial use.

SPDX-License-Identifier: Apache-2.0 OR MIT