fmg-mcp

An MCP (Model Context Protocol) server that drives Azgaar's Fantasy Map Generator in a real browser via Playwright, so Claude (or any MCP client) can generate maps, inspect them, and export screenshots / SVG / JSON.

FMG is a client-side web app with no public API, so this server works by puppeting an actual instance of the page — clicking buttons, filling inputs, and reading its in-memory JS state — rather than reimplementing its generation algorithms.

There are two ways to run this: locally over stdio (for Claude Desktop/Code) or remotely over HTTP (to use as a "custom connector" URL in claude.ai). Pick one.

Option A: Local, stdio (Claude Desktop / Claude Code)

cd fmg-mcp
npm install
npx playwright install chromium   # downloads a headless Chromium build
npm run build

Register it:

{
  "mcpServers": {
    "fmg": {
      "command": "node",
      "args": ["/absolute/path/to/fmg-mcp/dist/stdio.js"],
      "env": {
        "FMG_HEADLESS": "true",
        "FMG_OUTPUT_DIR": "/absolute/path/to/fmg-output"
      }
    }
  }
}

Environment variables (all optional):

• FMG_URL — override the FMG URL (defaults to the GitHub Pages instance).
• FMG_HEADLESS — "false" to watch the browser while it works. Defaults to headless.
• FMG_OUTPUT_DIR — where screenshots/exports are written. Defaults to ./fmg-output.

Option B: Remote, HTTP (claude.ai "Add custom connector")

This runs the same tools over Streamable HTTP at /mcp, so you can host it somewhere and give claude.ai the URL. It needs a real browser, so it must run on a container/VM host, not a serverless/edge platform.

Deploy on Render.com (free/starter tier, easiest)

1. Push this folder to a GitHub repo.
2. In Render: New > Blueprint, point it at the repo — it will pick up render.yaml and Dockerfile automatically and build the image.
3. Render auto-generates an AUTH_TOKEN env var for you (see the service's Environment tab) — copy it.
4. Once deployed, your MCP URL is https://<your-service>.onrender.com/mcp.

Deploy anywhere else that runs Docker (Fly.io, Railway, a VPS, etc.)

docker build -t fmg-mcp .
docker run -p 8787:8787 -e AUTH_TOKEN=$(openssl rand -hex 24) fmg-mcp

Put whatever host/domain that ends up behind at https://your-host/mcp.

Add it to claude.ai

Settings → Connectors → Add custom connector, then:

• URL: https://your-host/mcp
• If you set AUTH_TOKEN, choose the auth option that lets you supply a bearer token, and paste the token value in.

⚠️ Security note: anyone with the URL and token can drive a real browser through your server. Always set AUTH_TOKEN on anything reachable from the public internet — don't leave it unset outside of local testing.

Notes on the HTTP deployment

• Playwright's official Docker base image (mcr.microsoft.com/playwright) is used so Chromium and its OS dependencies are already present — no extra apt-get/playwright install step needed in the container.
• The server keeps one browser page per MCP session (keyed by the Mcp-Session-Id header the SDK manages automatically), so map state persists across tool calls within a conversation, same as the stdio version.
• Free hosting tiers that spin containers down when idle will lose in-memory map state between calls — fine for occasional use, but if you want state to reliably survive idle periods, use a plan that keeps the container warm.

Tools

Tool	What it does
open_map	Launches/reuses the browser session and waits for FMG to load. Call first.
new_map	Generates a new map, optionally with a specific seed and/or heightmap template.
get_map_info	Reads seed, dimensions, and counts of cultures/states/burgs/religions from the page state.
screenshot	Saves a PNG of the map (or full page) to the output directory.
export_svg	Saves the live map SVG to a .svg file.
export_json	Best-effort dump of FMG's internal pack/grid/notes data to JSON.
click	Clicks any element by CSS selector — for UI FMG doesn't have a dedicated tool for.
inspect_globals	Lists map-related window globals FMG currently exposes, to help you write run_js calls.
run_js	Evaluates arbitrary JS in the page (e.g. calling FMG's own save/generate functions directly).
close_browser	Closes the browser session.

A note on fragility

FMG doesn't publish a stable API, and its internal function/variable names and UI selectors have changed across versions over the project's history. The tools above use the most common/longstanding selectors and globals (#regenerateMap, window.pack, window.seed, etc.), but if the deployed version has drifted:

1. Use inspect_globals and run_js to poke around and find the current equivalents (e.g. run_js with "Object.keys(window).filter(k => /gener/i.test(k))").
2. Use click with browser devtools-inspected selectors as a fallback for any UI action not covered by a dedicated tool.

Example session

open_map
new_map { "seed": "123456789", "template": "Continents" }
get_map_info
screenshot { "fileName": "continents.png" }
export_svg { "fileName": "continents.svg" }