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

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

Document	Audience	Description
AGENTS.md	AI agents	Token-efficient usage guide, decision trees, error handling
docs/architecture.md	Developers & agents	System architecture diagram and communication flows
docs/tool-reference.md	Agents & developers	Compact parameter reference for all tools
docs/recipes.md	Agents & developers	Composable patterns for scenes, physics, lighting, scripting
docs/components.md	Agents & developers	O3DE component name catalog with dependency chains

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

Environment Variable	Description	Default
O3DE_ENGINE_PATH	Override automatic engine discovery	Auto-detected from manifest
O3DE_ENGINE_NAME	Select engine by name when multiple are registered	First valid engine
O3DE_EDITOR_HOST	Editor remote console host	127.0.0.1
O3DE_EDITOR_PORT	Editor remote console port	4600
O3DE_EDITOR_TIMEOUT	Editor command timeout (seconds)	10
O3DE_CMAKE_GENERATOR	CMake generator for builds	Auto-detected per platform
O3DE_CONFIGURE_TIMEOUT	CMake configure timeout (seconds)	600
O3DE_BUILD_TIMEOUT	CMake build timeout (seconds)	1800
O3DE_EXPORT_TIMEOUT	Project export timeout (seconds)	3600

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