hma-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Why
HMA already understands a ROM: it knows where the Pokémon stats table is, which bytes are a type, and how to recompile a script and move it if it grows. hma-mcp gives an AI assistant that same understanding, so you can describe a change in plain words and have it done correctly:
No GUI clicking. The assistant calls HMA's engine directly, without driving the HMA window.
Names, not bytes. Types, moves, species and items read and write as names (
FIRE,THUNDERBOLT). A typo is rejected with suggestions instead of writing garbage.Repointing handled. When a script or text grows, HMA's engine finds free space, moves it, and updates every pointer.
Safe by default. Nothing touches the disk until you say
save, the first save backs up your original, and every edit is one undo away.
Related MCP server: PokeMCP
What it looks like
These are real results from a FireRed (U) 1.0 test run:
You: Open
C:/hacks/firered.gbaand show me Bulbasaur's base stats.Claude: (
open_rom,read_table) BULBASAUR: 45 HP / 49 Atk / 49 Def / 45 Spe / 65 SpA / 65 SpD, GRASS/POISON.You: Make Charmander Fire/Dragon.
Claude: (
write_table_field) CHARMANDERtype2: FIRE → DRAGON. Not saved yet; say "undo" to revert.You: Add a second chime to the Safari Zone time's-up script.
Claude: (
decompile_script,compile_script) The script grew from 17 to 20 bytes and didn't fit, so HMA moved it from1BFBC5to free space at71A280and updated its 1 pointer. The anchorscripts.fromthumb.safari.endfollows it.You: Save.
Claude: (
save) Savedfirered.gbaandfirered.toml. Your original is backed up in.hma-mcp-backups/.
Quick start
You'll need a ROM you dumped yourself.
1. Get the server
Download the latest release. The builds are self-contained, so you don't need .NET installed.
You use | Download |
Claude Desktop | the |
Anything else |
|
Keep the hma-mcp executable next to its resources/ folder. On macOS, a downloaded build is quarantined until you run xattr -dr com.apple.quarantine <folder>.
git clone --recurse-submodules https://github.com/dewayneku/hma-mcp.git
cd hma-mcp
dotnet publish src/HmaMcp -c Release -o ~/.local/share/hma-mcpOn Windows, -o %LOCALAPPDATA%\hma-mcp is a good spot, or run scripts/install.ps1, which also works while an MCP client is using the server. Publish outside the repo: an MCP client keeps the server running, and on Windows a running .exe can't be overwritten, so pointing a client at bin/ breaks your next build. To update, pull, close your MCP client (or start a new session), and run the same publish command again.
2. Connect your client
Claude Code:
claude mcp add --scope user hma -- "C:/Users/you/AppData/Local/hma-mcp/hma-mcp.exe"--scope user makes it available in every project. Servers load when a session starts, so open a new one afterwards.
Claude Desktop (if you didn't use the .mcpb) and other MCP clients:
{
"mcpServers": {
"hma": { "command": "C:/Users/you/AppData/Local/hma-mcp/hma-mcp.exe" }
}
}Some clients, like ChatGPT (Developer Mode), only connect to MCP servers on the internet over HTTPS. hma-mcp has an HTTP mode for them, plus a tunnel so the client can reach your PC:
hma-mcp --http --rom-dir "C:/hacks"cloudflared tunnel --url http://127.0.0.1:3333The server prints a URL with a secret token, like http://127.0.0.1:3333/mcp/3f9c.... Give your client the same path on the tunnel's address: https://<random>.trycloudflare.com/mcp/3f9c.... (ngrok and other tunnels work too.)
The token is the password. Requests without it get a 404. A new one is made each run; pass
--token <at least 16 characters>or setHMA_MCP_TOKENto keep one. Clients that send headers can useAuthorization: Bearer <token>on/mcpinstead.--rom-diris the only folder it can touch. ROMs, PNGs and saves must be inside it, and paths are shown relative to it.It listens on 127.0.0.1 only. The tunnel is the only way in, and it lasts only while it's running. Stop it when you're done.
All tools work the same over HTTP. Clients that don't display images still get the text part of image tools. Tested with the included HTTP test client; ChatGPT's own setup steps change often, so check OpenAI's help center.
Then just ask, for example:
"Open my ROM and list every table with 'items' in its name."
"Give Pikachu 90 base Sp. Atk and make it Electric/Steel."
"Decompile
scripts.newgame.setflagsand explain what it does.""Show me Charmander's shiny sprite, then make its flame blue."
"Draw Pallet Town with its NPCs."
"Copy one of Pallet Town's houses into the empty space at the bottom, then widen Route 1 by two blocks."
"Make a new route east of Pallet Town that looks like Route 1."
"Import the ground and the dead trees from my tileset PNG into that route, then put a river and a grove on it."
"Find 512 bytes of free space."
Tools
Tool | What it does | |
📂 |
| Open a |
🔎 |
| Search named anchors: |
🧭 |
| Anchor or address → what's there: type of data, table row and field, pointer count |
📋 |
| Table layout, and rows as JSON: enums as names, flag sets as lists, packed fields as objects, learnsets and teams as text; filter rows with |
✏️ |
| Set one field by row number or row name ( |
🗺️ |
| Find a map by name ( |
🖼️ |
| See any sprite, tileset, tilemap or palette as an image (the assistant sees it too), save it as PNG, and import an edited PNG with HMA's palette fitting |
🎨 |
| A palette's colors as |
🏞️ |
| A picture of a map, with NPCs and event markers |
🧱 |
| A map's blocks and movement permissions as hex grids; paint blocks (copy a building from one spot to another); see the tiles a map can use |
🚪 |
| Add or remove NPCs, warps, triggers and signs; grow or shrink a map (events and connections stay in place) |
🆕 |
| New maps modeled on an existing one (its tilesets, music, weather); join or separate neighboring maps, both sides at once |
🕊️ |
| Make a map a Fly destination; put it on the Town Map |
🏷️ |
| Region names (what a map shows on entry, on the Town Map, as a met location): which are free, and new names in free slots |
🧍 |
| A labeled sheet of NPC sprites, to pick one by number |
🧩 |
| What a block is made of (8 tiles, 2 layers) and how it behaves (grass, water, door, ...); change either |
🎨 |
| Turn a top-down PNG tileset (or several images) into a map's own tileset: ground blocks, and objects like trees and houses drawn over them with transparency; colors fitted to the GBA, duplicate and mirrored tiles shared |
💬 |
| Game text at an address (a script's message, say); longer text is moved and every pointer to it updated |
📜 |
| Event, battle, animation and trainer-AI scripts, with automatic repointing |
⌨️ |
| Type into HMA's hex view using its full edit language ( |
🧱 |
| Raw access, for when you need it |
↩️ |
| One step per tool call, even when HMA records several internally |
💾 |
| Write the ROM and its |
Games
HMA supports FireRed, LeafGreen, Emerald, Ruby and Sapphire, and hacks of them. FireRed (U) 1.0 is tested end to end with hma-mcp, and Emerald (U) passes a shorter check (tables, maps, scripts, text, save). Ruby, Sapphire and LeafGreen use the same engine but haven't been run through hma-mcp's tests yet. Reports are welcome.
How it works
flowchart LR
A["Claude / any MCP client"] <-- "MCP over stdio" --> B["hma-mcp<br/>(46 tools)"]
B --> C["HexManiac.Core<br/>(HMA's engine, built from source)"]
C <--> D[("your ROM .gba<br/>+ HMA .toml metadata")]HMA is a git submodule (
external/HexManiacAdvance), and its core library is compiled from source bysrc/HexManiac.Core.Build, so the server runs exactly the editor's code.ROMs open headlessly, the same way HMA's own test suite opens them.
compile_scriptfollows HMA's code editor step for step: compile, move if it grew, update pointers, and keep any sub-scripts the edit left orphaned.To move to a newer HMA, run
git submodule update --remote external/HexManiacAdvance.
Problems found in HMA itself while building this, with fixes, are tracked in docs/hma-upstream-notes.md.
Testing
python tests/smoke.py <path-to-hma-mcp> [path/to/firered.gba]With a ROM: copies it to a temp folder and edits only the copy. Checks reads, writes, enum validation, undo/redo, a script that has to move to free space,
hma_edit, and a save → reopen round trip (written against FireRed (U) 1.0).tests/smoke_emerald.pyruns a shorter version on Emerald (U).Without a ROM: checks the MCP handshake and tool list, and opens a blank ROM so HMA loads all of its reference data. CI runs this on Windows, Linux and macOS.
HTTP mode:
python tests/smoke_http.py <path-to-hma-mcp> [firered.gba]checks the token gate, the ROM folder limit and the tools over HTTP.
Legal
hma-mcp doesn't include, download or distribute ROMs, and never will. Use it with ROMs you dumped from games you own. Pokémon is a trademark of Nintendo, Creatures Inc. and GAME FREAK inc.; this project isn't affiliated with or endorsed by them.
Credits
HexManiacAdvance by haven1433 and contributors (MIT). All of the ROM knowledge here comes from HMA.
MIT licensed; see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Savecraft serves real save game data and expert game knowledge to AI assistants.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables programmatic control of the mGBA emulator for Game Boy, Game Boy Color, and Game Boy Advance games, including screenshot capture, memory reading, sprite data dumping, and custom Lua script execution for automated testing and game analysis.66-
- FlicenseAqualityDmaintenanceEnables AI assistants to play Pokemon Fire Red through the mGBA emulator by providing tools for button inputs and screenshots. It allows for direct reading of real-time game state from RAM, including party information, player location, and battle status.103-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to perform headless reverse engineering of retro game ROMs using Ghidra, with automated platform detection and triage.28 PyPI1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read and edit RPG Maker VX Ace and VX project data files directly, including databases, maps, events, scripts, and validation, without requiring Ruby.3MIT