porymap-mcp

An MCP server that lets Claude, or any MCP client, paint, render and critique Porymap-compatible maps for Pokémon Gen 3 decompilation projects.

Littleroot Town from pokeemerald-expansion, rendered by the server's render_map tool with include_border=True. Pixel-identical to Porymap's own PNG export.

What it does

• Reads a pokeemerald-family project: maps, layouts, tilesets, metatiles, events, prefabs.
• Writes the same files Porymap writes: metatiles, rectangles, flood fills, borders, prefabs, warps, NPCs, signs (with a script stub), triggers, new maps and map-group registration. Writes are atomic.
• Renders maps, regions and single metatiles to PNG and returns them as MCP image content blocks. Output is pixel-identical to Porymap's own export on a 5-map reference corpus (Littleroot Town, Route 101, Granite Cave 1F, Battle Frontier Outside East, plus a synthetic edge case).

Route 101, same tool and settings, also pixel-identical to Porymap's export.

Porymap does not need to be running. Open the project in Porymap whenever you like: your manual workflow is untouched.

It does not edit tilesets (creating new metatiles stays in Porymap), and it does not generate graphics, music or story content.

Compatibility

Built and tested against rh-hideout/pokeemerald-expansion, the base most active hacks use today (ADR-0002). Vanilla pret/pokeemerald uses the same file formats and loads the same way. Bit masks and paths are read from your porymap.project.cfg, so nothing is hard-coded per fork. pokefirered and pokeruby projects are recognised but not covered by the test corpus yet.

Install

pip install "porymap-mcp[render]"

Or run it with no install step via uv:

uvx --from "porymap-mcp[render]" porymap-mcp

The render extra pulls in Pillow and numpy for the three render tools. Without it (pip install porymap-mcp), the 21 read/write tools work on their own.

Requires Python 3.11+.

Register it with your MCP client

Claude Code:

claude mcp add porymap -- uvx --from "porymap-mcp[render]" porymap-mcp

Claude Desktop (claude_desktop_config.json) or any client that takes a JSON server list:

{
  "mcpServers": {
    "porymap": {
      "command": "uvx",
      "args": ["--from", "porymap-mcp[render]", "porymap-mcp"]
    }
  }
}

If you installed with pip, use "command": "porymap-mcp" (or "python" with "args": ["-m", "porymap_mcp"]).

No environment variables are needed: the project path is passed on every tool call, so one server can work on several projects.

First map in 5 minutes

With the server registered, ask your agent:

Open my pokeemerald project at ~/code/pokeemerald-expansion. Create a 20×20 map called LakesideTown in the gMapGroup_TownsAndRoutes group, using gTileset_General + gTileset_Petalburg. Stamp a small house at (3, 4), put a sign next to its door that says "Welcome to Lakeside!", then render the map and critique it.

The agent will typically:

1. Call get_project_info to confirm the project loads and read its config.
2. Call list_tilesets to check that both tilesets exist.
3. Call create_map, which writes data/maps/LakesideTown/map.json, data/layouts/LakesideTown/map.bin and border.bin, and registers the map in data/layouts/layouts.json and data/maps/map_groups.json.
4. Call paint_prefab with house_small at (3, 4): a 3×3 footprint with its door at (4, 6).
5. Call add_sign at (3, 7). This appends the event to map.json and generates a script stub (poryscript, or .inc if your project has use_poryscript=0).
6. Call render_map and look at the PNG it gets back.

Every write tool returns the list of files it modified. Open the project in Porymap, or rebuild your ROM: the map is there.

Tileset labels. Littleroot Town, Oldale Town and Petalburg City all use gTileset_General + gTileset_Petalburg, in both vanilla pokeemerald and pokeemerald-expansion. There is no gTileset_LittlerootTown. If your fork renames or adds tilesets, ask the agent to call list_tilesets first and pick from what it returns.

Self-critique loop

Because renders come back inside the tool response, the agent can look at its own work. It paints the map, renders it, critiques the image against a 12-criterion Gen 3 design rubric (path geometry, tile variety, building placement, border softness, …), fixes the top issues and renders again.

Iteration 1: first draft	Iteration 2: after one critique pass
Score 7 / 36	Score 21 / 36

The demo runs on a small synthetic tileset made of flat colour blocks, so it works without a pokeemerald checkout. On a real project, renders use your actual tilesets, as in the Littleroot Town image above. Runnable walkthrough: examples/04_render_loop/.

Tools

24 tools. Each tool's docstring is what your agent reads, and the full contracts are in the ADRs listed below. Every tool takes project_path as its first argument.

The three render tools accept overlays (collision, elevation, grid, events) and a scale factor. All seven map-mutation tools and all five event tools accept return_render=True, which adds the post-edit render to the same response and saves a round trip.

Design records

Every decision that is hard to reverse is written up as an ADR in docs/decisions/:

• ADR-0001: FastMCP as the MCP framework
• ADR-0002: pokeemerald-expansion as the primary target
• ADR-0003: a single Project entry point, config-driven formats
• ADR-0004: where tileset metadata comes from
• ADR-0005, ADR-0006, ADR-0007: discovery, mutation and event tool contracts
• ADR-0008: prefab library and paint_prefab
• ADR-0009: why live Porymap hot-reload was dropped
• ADR-0010: renderer design, including the four corrections found while validating against Porymap

The project's vision document is MCP_PORYMAP.md (in French).

Prefabs

paint_prefab ships with three stamps: single_tree, flower_patch and house_small. Their metatile IDs follow vanilla gTileset_General conventions. If your fork uses custom tilesets, register your own prefabs in porymap_mcp.prefabs.LIBRARY (a plain dict). See ADR-0008.

Develop

git clone https://github.com/hugomrts/porymap-mcp
cd porymap-mcp
uv sync --all-extras        # or: pip install -e ".[dev]"
pre-commit install
pytest

CI blocks on ruff check, ruff format --check, mypy --strict and the full test suite (Linux and macOS, Python 3.11 to 3.13). CLAUDE.md describes the conventions used to develop this repo with Claude Code, including the sub-agents in .claude/agents/, which anyone can reuse.

Acknowledgements

• Porymap by Marcus Huderle: the editor whose files this server writes.
• pret: the decompilation projects that make all of this possible.
• rh-hideout: the pokeemerald-expansion fork.
• FastMCP: the Python MCP framework used here.

License

MIT