hma-mcp
by dewayneku
README.md
<p align="center">
<img src="assets/banner.svg" alt="hma-mcp: let your AI assistant hack GBA ROMs, powered by HexManiacAdvance" width="100%">
</p>
<p align="center">
<a href="https://github.com/dewayneku/hma-mcp/actions/workflows/ci.yml"><img src="https://github.com/dewayneku/hma-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<img src="https://img.shields.io/badge/.NET-8.0-512BD4?logo=dotnet&logoColor=white" alt=".NET 8">
<img src="https://img.shields.io/badge/MCP-server-6E56CF" alt="MCP server">
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-555" alt="Windows, Linux, macOS">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
</p>
<p align="center">
<b>An <a href="https://modelcontextprotocol.io">MCP</a> server for GBA Pokémon ROM hacking.</b><br>
Claude (or any MCP client) reads and edits your ROM through the engine behind <a href="https://github.com/haven1433/HexManiacAdvance">HexManiacAdvance</a>:<br>
the same anchors, tables, script compiler and repointing, with every edit undoable and saves that open straight back up in HMA.
</p>
<p align="center">
<a href="#quick-start">Quick start</a> ·
<a href="#what-it-looks-like">Example</a> ·
<a href="#tools">Tools</a> ·
<a href="#how-it-works">How it works</a> ·
<a href="CONTRIBUTING.md">Contributing</a>
</p>
---
## 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.
## What it looks like
These are real results from a FireRed (U) 1.0 test run:
> **You:** Open `C:/hacks/firered.gba` and 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`)* CHARMANDER `type2`: 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 from `1BFBC5` to free space at `71A280` and updated its 1 pointer. The anchor `scripts.fromthumb.safari.end` follows it.
>
> **You:** Save.
>
> **Claude:** *(`save`)* Saved `firered.gba` and `firered.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](https://github.com/dewayneku/hma-mcp/releases/latest). The builds are self-contained, so you don't need .NET installed.
| You use | Download |
|---|---|
| Claude Desktop | the `.mcpb` for your system (`win32`, `darwin` for Apple Silicon Macs, `linux`), then double-click it |
| Anything else | `hma-mcp-<system>.zip` / `.tar.gz`, unpacked somewhere permanent, e.g. `%LOCALAPPDATA%\hma-mcp` or `~/.local/share/hma-mcp` |
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>`.
<details>
<summary><b>Or build it from source</b> (needs the <a href="https://dotnet.microsoft.com/download/dotnet/8.0">.NET 8 SDK</a>)</summary>
```bash
git clone --recurse-submodules https://github.com/dewayneku/hma-mcp.git
cd hma-mcp
dotnet publish src/HmaMcp -c Release -o ~/.local/share/hma-mcp
```
On 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.
</details>
### 2. Connect your client
**Claude Code:**
```bash
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:**
```json
{
"mcpServers": {
"hma": { "command": "C:/Users/you/AppData/Local/hma-mcp/hma-mcp.exe" }
}
}
```
<details>
<summary><b>ChatGPT and other clients that connect by URL</b></summary>
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:
```bash
hma-mcp --http --rom-dir "C:/hacks"
```
```bash
cloudflared tunnel --url http://127.0.0.1:3333
```
The 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 set `HMA_MCP_TOKEN` to keep one. Clients that send headers can use `Authorization: Bearer <token>` on `/mcp` instead.
- **`--rom-dir` is 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.
</details>
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.setflags` and 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_rom` · `rom_info` · `close_rom` | Open a `.gba`, with HMA's `.toml` metadata if it's there |
| 🔎 | `list_anchors` | Search named anchors: `data.pokemon.stats`, `scripts.…`, `graphics.…` |
| 🧭 | `resolve` | Anchor or address → what's there: type of data, table row and field, pointer count |
| 📋 | `describe_table` · `read_table` | 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 `where` (`bank=3, map=19`) |
| ✏️ | `write_table_field` | Set one field by row number or row name (`CHARMANDER`), checked against the field's size; also learnsets, TM lists, trainer teams |
| 🗺️ | `find_map` · `map_events` | Find a map by name (`PALLET TOWN` → `3.0`), then list its NPCs, warps, trigger scripts, signs and connections, with addresses ready for `write_table_field` (to move or change one) |
| 🖼️ | `view_image` · `import_image` | 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 |
| 🎨 | `read_palette` · `write_palette` | A palette's colors as `#RRGGBB`, and which graphics use it |
| 🏞️ | `render_map` | A picture of a map, with NPCs and event markers |
| 🧱 | `read_map_blocks` · `paint_map_blocks` · `view_blockset` | 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_map_event` · `remove_map_event` · `resize_map` | Add or remove NPCs, warps, triggers and signs; grow or shrink a map (events and connections stay in place) |
| 🆕 | `create_map` · `connect_maps` · `disconnect_maps` | New maps modeled on an existing one (its tilesets, music, weather); join or separate neighboring maps, both sides at once |
| 🕊️ | `add_fly_spot` · `read_town_map` · `paint_town_map` | Make a map a Fly destination; put it on the Town Map |
| 🏷️ | `list_region_names` · `add_region_name` | 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 |
| 🧍 | `view_overworld_sprites` | A labeled sheet of NPC sprites, to pick one by number |
| 🧩 | `read_block` · `write_block` · `list_block_behaviors` · `view_tiles` | What a block is made of (8 tiles, 2 layers) and how it behaves (grass, water, door, ...); change either |
| 🎨 | `import_tileset` | 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 |
| 💬 | `read_text` · `write_text` | Game text at an address (a script's message, say); longer text is moved and every pointer to it updated |
| 📜 | `decompile_script` · `compile_script` | Event, battle, animation and trainer-AI scripts, with automatic repointing |
| ⌨️ | `hma_edit` | Type into HMA's hex view using its full edit language (`^anchor`, `<pointer>`, `"text"`) |
| 🧱 | `read_bytes` · `write_bytes` · `find_free_space` | Raw access, for when you need it |
| ↩️ | `undo` · `redo` | One step per tool call, even when HMA records several internally |
| 💾 | `save` | Write the ROM and its `.toml`; the first save backs up the original |
### 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
```mermaid
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 by `src/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_script` follows 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](docs/hma-upstream-notes.md).
## Testing
```bash
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.py` runs 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](.github/workflows/ci.yml) 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**](https://github.com/haven1433/HexManiacAdvance) by haven1433 and contributors (MIT). All of the ROM knowledge here comes from HMA.
- [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk).
MIT licensed; see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues