Age of Mythology: Retold Editor MCP
[!IMPORTANT] Unofficial community project. Not affiliated with, endorsed or supported by Microsoft.
Let an AI agent (Claude, ChatGPT, Copilot, etc.) build scenarios in the Age of Mythology: Retold scenario editor. The agent can place units and buildings, paint terrain, shape elevation, move the camera, edit triggers, set up players and diplomacy, take screenshots and more.
It works through the game's own editor commands. It doesn't patch the game or bypass any protection.
[!WARNING] This is beta software. If a tool fails or crashes the game, ask your agent to open an issue in this repo. If your agent keeps falling back to screenshots and mouse clicks, ask it which tool it was missing and consider opening an issue or PR for it.
Requirements
- Windows x64
- Age of Mythology: Retold (a supported game version)
- Node.js 20 or newer (for the npm install)
- An MCP-capable AI client
Install
Add this to your MCP client's configuration:
{
"mcpServers": {
"aom-editor": {
"command": "npx",
"args": ["-y", "aom-retold-editor-mcp"]
}
}
}
If the game isn't installed in Steam's default location, add the path to the game exe:
"args": ["-y", "aom-retold-editor-mcp", "--exe", "D:\\Games\\Age of Mythology Retold\\AoMRT_s.exe"]
Then start the game, open the scenario editor, and ask your agent to build something.
More install options are in npm/README.md.
Without Node.js
Download AomRetoldMapEditorMcp-win-x64.zip from Releases, extract it and point your MCP client at AomMcp.exe (add --exe <game path> if needed). Nothing else to install.
Optional: game-data catalogs
Some tools look up game data, like exact unit names for a pantheon, gods, techs and terrain types, or what every editor dialog contains and which commands its buttons run (editor_dialogs). They need metadata generated from your own game files. Ask the agent to run editor_generate_catalog (uses the bundled CryBar library).
After a playtest, editor_xs_diagnostics reads the game's own XS compile errors from MythLog.txt, and editor_xs_check is an offline heuristic lint (it never replaces the game log). editor_help serves detailed topic guides and editor_scenario_digest summarizes a saved scenario in one call. Bulky read tools accept fields and saveTo to keep results small.
To share a finished scenario, editor_build_campaign packages saved scenarios as a campaign mod for the Campaigns menu. It also copies the AI and trigger scripts they need from your profile, so the mod works with nothing else installed. Rerun it with operation=update after changes.
To hand the agent positions, write object notes in the editor and save: editor_unit_notes scenarioPath="latest" reads them from your newest save and groups near-identical notes. Trigger edits keep track of the export they started from, so an import given that base refuses when the editor's triggers changed in the meantime.
For writing AI, random map and trigger scripts, editor_xs_api looks up engine functions and the game's shipped script libraries. The project ships only their signatures and its own short summaries; the game's official help text is read from your install.
Good to know
- Offline editor only. Never use it in multiplayer.
- Save your work first. The agent can change and delete things. Edits aren't atomic, and a failed step isn't rolled back.
- Game updates can break support until the project is updated for the new build. Unknown versions are refused instead of guessed.
- The server starts with a smaller core tool set (84 tools). From core the agent can still find and call any of the 900+ full tools through
editor_search_toolsandeditor_call, or switch to the full set when needed. - Normal and alternative editor UIs are both supported. Best tested at 2560×1440 and 1920×1080.
- Focus. Screenshots and screen reads work while another window (e.g. your terminal) is in front. Tools that click or type bring the game to the front first. If Windows refuses that (
FOCUS_NOT_GRANTED), setAOM_MCP_FOCUS=assertivein the server environment: it tries harder (including briefly minimising a terminal) and hands focus back to your previous window after each call or batch.editor_focuskeeps the game in front.
More docs
- Technical reference: building from source, the full tool list, the generator and what's been verified
- TOOLS.md: reference for every tool
- research/: detailed notes and evidence
- Releasing: for maintainers
Credits
Thanks to CryShana for CryBar / CryBarEditor, whose library (git submodule lib/CryBarEditor, bundled in releases) reads the game's data archives.
License
MIT. Game assets, CryBar and third-party components keep their own licenses. This license doesn't imply any Microsoft endorsement.
This project was quickly "vibe-coded" using ChatGPT 6.1-sol and then Claude Opus 5.5.