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.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
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.
Automate Open 3D Engine with AI — an MCP server for editor control, project & build management
96 tools across seven 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 toolsEditor Automation (41 tools, requires a running O3DE Editor with the AiCompanion + EditorPythonBindings gems):
azlmbr API)get_scene_snapshot / get_entity_tree / get_entity / validate_scene), no editor Python involved, available even in the gem's secure modeset_parentcreate_entity, set_transform and delete_entity try the gem's native request types first (gem 0.5.0 or later, validated in C++, available in secure mode) and fall back to editor Python on older gems or the legacy transportsave_prefab reports that and names the owning prefab)begin_session / exec_in_session / get_session_vars / end_session) that keep Python state alive across callsEngine Introspection (3 tools):
azlmbr stubs and live from the editorProject & Build Management (17 tools, CLI-based, no editor required):
build_project) or in the background (start_build / get_build_status)Asset Pipeline (9 tools; 5 need no editor):
wait_for_asset, which waits until a specific asset is built or reports why it failedTrack View (8 tools, requires a running editor):
azlmbr.legacy.trackview, no gem needed. Track and keyframe authoring are not exposed (the reflected API makes them unreliable to drive)Animation (17 tools, requires a running editor):
O3DE_ENGINE_PATH env var)
~/.o3de/o3de_manifest.json%USERPROFILE%\.o3de\o3de_manifest.jsonget_capabilities() to check what's available.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 .
o3de-mcp
Add to your MCP config (or use a project-level .mcp.json):
~/.claude/mcp.json%USERPROFILE%\.claude\mcp.json{
"mcpServers": {
"o3de": {
"command": "o3de-mcp"
}
}
}
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.
Add to your Claude Desktop config:
{
"mcpServers": {
"o3de": {
"command": "o3de-mcp"
}
}
}
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
# 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/
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.
GitHub Actions runs lint, type checking, tests, and SBOM generation on every push and PR to main. See .github/workflows/ci.yml.
json.dumps / json.loads when passed into editor scripts, never raw string interpolation.Progressive walkthroughs from project creation to a complete game:
Editor timeouts: the editor runs each submitted script synchronously and does not reply until it finishes, so
O3DE_EDITOR_TIMEOUTis 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 separateO3DE_EDITOR_CONNECT_TIMEOUTand the fast-fail window, so a large command timeout costs nothing on the healthy path.run_editor_pythonalso accepts a per-calltimeoutargument.
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 pointO3DE_EDITOR_HOSTat a remote machine, setO3DE_EDITOR_TLS=1andO3DE_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:
~/.o3de/o3de_manifest.json%USERPROFILE%\.o3de\o3de_manifest.jsonThis 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
Automate Open 3D Engine with AI — an MCP server for editor control, project & build management
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
O3de 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 Automate Open 3D Engine with AI — an MCP server for editor control, project & build management