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

66 tools across five categories. See docs/tool-reference.md for every parameter.

Capability Detection (1 tool):

• get_capabilities: check editor connectivity, whether the AiCompanion gem's AgentServer is answering (with its gem, API and protocol versions), and CLI availability before using other tools
• Dynamic tool discovery: new tools are automatically reported

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

• Execute arbitrary Python scripts inside the editor (azlmbr API)
• Scene snapshot, entity tree and scene validation served natively by the AiCompanion gem's C++ (get_scene_snapshot / get_entity_tree / validate_scene), no editor Python involved, available even in the gem's secure mode
• List, create, delete, and duplicate entities; reparent with set_parent
• Add and remove components, get/set component properties, assign assets by path
• Get and set transforms
• Create, save, and instantiate prefabs
• Create, load, save, and query levels
• Viewport camera control, entity focus, and screenshot capture
• Run console commands, get/set CVARs
• Enter/exit game mode, undo/redo
• Persistent scripting sessions (begin_session / exec_in_session / get_session_vars / end_session) that keep Python state alive across calls
• Fast-fail when editor is unreachable (avoids repeated timeouts)

Engine Introspection (3 tools):

• EBus schema discovery, both from generated azlmbr stubs and live from the editor
• RenderDoc frame capture

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

• Discover local O3DE engine installations (multi-engine support), register engines, select the active one
• 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, either blocking (build_project) or in the background (start_build / get_build_status)
• Export projects for distribution

Asset Pipeline (5 tools, no editor required):

• Asset Processor status, asset refresh, and wait-for-completion
• Tail editor and Asset Processor logs, filter for errors

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 o3de-mcp

Or run it without installing, straight from an MCP client config, with uv:

uvx o3de-mcp

To work on o3de-mcp itself, install from a checkout instead:

pip install -e .        # or: 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"
    }
  }
}

Agent skill: headless verification and editor automation

skills/o3de-headless-and-editor-automation/ is an Agent Skill (a SKILL.md plus reference notes and scripts) that teaches an agent the repeatable workflow around this server on Windows and Linux: AssetProcessor-first launch order and how to tell when it is idle, rendering a level on the real GPU and capturing it with ffmpeg (Xvfb when there is no monitor), in-renderer screenshots from editor Python, driving the editor through o3de-mcp and the AiCompanion gem, wiring asset GUIDs into prefab JSON offline, and proving engine changes with a ScriptContext test. It records the traps that cost hours (the prefab segfault on a missing template, killing your own shell by command-line pattern, the AP idle line living in AP_GUI.log). The Linux path has been run end to end; the Windows path is written from the engine layout and still needs a run on a Windows machine.

Install it by copying or symlinking the directory into your skills folder, then invoke it with /o3de-headless-and-editor-automation:

ln -s "$(pwd)/skills/o3de-headless-and-editor-automation" ~/.claude/skills/

Other clients that read the Agent Skills layout can point at the same directory.

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, without the dev and build tooling.

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, and 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.

Editor TLS: the connection is plaintext by default, which is the right default for the normal case of an editor on 127.0.0.1. If you point O3DE_EDITOR_HOST at a remote machine, set O3DE_EDITOR_TLS=1 and O3DE_EDITOR_TLS_VERIFY=1. Enabling TLS on its own leaves certificate and hostname checking off, which encrypts the channel but does not authenticate the peer.

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