fvtt-mcp-artificer
An MCP server for generating and editing Foundry VTT art with Gemini image models, including token cutouts and setup diagnostics.
Generate item/spell icons, tokens, props, portraits, and illustrations from prompts, with optional style/character/object/pose references.
Edit existing images to change one detail, fix flaws, refresh or restyle tokens, redress a token into another character, and restyle battlemaps or overland maps while preserving layout.
Cut token backgrounds to alpha on a square Foundry-ready canvas using chroma keying or rembg, with a preview for edge checking.
Create consistent art sets across tokens, portraits, illustrations, and maps using reference images.
Run an anatomy judge on tokens and portraits to flag limb, face, object, and facing issues.
Use the status tool to check API key, reachable models, output folder, Python cutout dependencies, and estimated session spend.
Allows generating and editing Foundry VTT art assets (icons, tokens, portraits, illustrations, cutouts) using Google's Gemini image models.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fvtt-mcp-artificer Generate a portrait of a grizzled dwarven ranger for my NPC"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fvtt-mcp-imagegen
An MCP server that lets Claude make art for your Foundry VTT table using Google's Gemini image models (Nano Banana). Four tools, one API key, no GPU.
Claude Code drives it. The server is registered as imagegen,
and its illustration-builder skill grounds every piece in what your world already says and
shows. Claude writes the prompt, the server renders it, Claude looks at the result and fixes what
is wrong, and the finished file lands on disk ready to upload into Foundry.
What you can make
Item, spell, and feature icons. Twenty icons from one style line come back as one matching set. About 3 cents each.
Tokens. Top-down, full-body, cut to transparency, centred on a square so Foundry's scale 1.0 is right: 512 px, or 1024 px for Large and bigger creatures. Humanoids face up at the camera; beasts are seen along the back. No shadow, and nothing ever clips off the edge: a render with a sword or wing cut by the frame is redone, and refused if it clips twice. Hand it one of your existing tokens as a style reference and new ones match the angle and look. About 3 cents each.
Token refreshes. Point it at an old, low-res token and it repaints it at higher quality while keeping the pose, silhouette, design, and colours your players know. It can also turn one creature into another in the same pose (a rat's token into a squirrel).
Token redresses. Start from a token you already have as the prototype and change who it is: "make this a Sharran cleric, black armour, a morningstar instead of the club". The pose, camera angle, and cut stay; the costume, gear, and figure change to match the actor it is now for. One stock token becomes the specific NPC in your world without a word of prompt about framing.
Token restyles. The same trick as battlemaps, for a whole bestiary. Tokens gathered from different packs (Immortal Nights, Forgotten Adventures, a few you drew yourself) do not match on one map. Hand it one token as the style reference and run the rest through, and they come back in one consistent look, each still recognisably the creature it was.
Props. Map dressing placed as tiles: furniture, barrels, trees, anvils. Seen straight down, object only, cut to transparency at the tile size (300 px per grid cell, from a
footprintlike"2x1"). Refreshing an existing prop returns it at the file's exact pixel size in the same spot on its canvas, so it replaces the old one one for one.Battlemap restyles. Repaint a map you bought (Tom Cartos, Mad Cartographer, anything) in one consistent painted style, with every wall, door, and object exactly where it was, so the walls and lights already traced over it in Foundry still fit. The result lands on the source's own pixel grid. An old low-res map comes back at a whole-number upscale (a 1125×1500 map at 3375×4500). Every render is checked against the original, and one whose layout moved is redone once, then refused. Maps ship as WebP, about 4 MB where a PNG would be 40 to 70. About 11 cents a map.
Overland maps. A regional or world map from a sourcebook or a sketch, repainted in the house style with the geography locked and every label, marker, road, compass rose, and scale bar painted out. Names go back on afterwards by script, spelled right and movable, instead of being left to the model. A busy map takes two or three passes to come clean; each is about 11 cents.
Portraits. Actor sheet art at 3:4. Hand it a previous portrait or two as style references and the new one matches your table's look.
Illustrations. Player handouts and scene splashes at 2560×1600. Hand it your party's portraits as character references and they keep their faces in group scenes.
Illustrated session records. With
fvtt-mcp-sessionscribealongside, the recap and GM notes it writes after a session come back illustrated: Claude picks the moments from the record, checks where each one happened against the transcript, attaches the portraits and tokens of everyone in the scene so the same faces recur from one week to the next, and drops the finished plates into the journal and the recap. The worked example is the concluded Greenrest campaign: every recap carries eight or nine plates, and the same shelf of references went on to illustrate the campaign's book.Edits. Change one thing about an existing image and keep the rest: swap a weapon, recolor a cloak, add a scar, fix an extra limb.
Cutouts. Knock the background off any token image you already have.
Related MCP server: Foundry VTT MCP Bridge
The tools
tool | what it does |
| Render one asset from a prompt. |
| Apply one instruction to an existing image and keep everything else. Token edits are prompted the way you would type in the Gemini app and re-cut automatically: a world token, a library token or a capture of your own is restyled in place with its pose and camera kept, and crops of signature gear can ride along as |
| Cut a token's background to alpha and deliver it on a square canvas. |
| Setup doctor: key present and accepted, models reachable, output folder writable and outside git, cutout Python ready; estimated spend this session. |
Every call returns the file path, the pixel size, and an estimated cost.
Models and cost
Everything runs on Nano Banana 2.1 (gemini-nano-banana-2.1) by default: roughly 3 cents for
an icon or token, 5 cents for a portrait, 11 cents for an illustration.
Nano Banana Pro (Gemini 3 Pro Image) is available for about double at 4K and four times at 1K. It is stronger on crowded multi-figure scenes and images with legible text. Claude will not use it unless you say so: a Pro call refuses without an explicit confirm and tells you the price first.
Prices are Google's published per-image rates and may change. The server keeps a running estimate; your actual bill is in the Google Cloud console.
Requirements
Node.js 22 or newer.
A Gemini API key from Google AI Studio with billing enabled: the image models have no free tier. Prepaid credit with auto-reload off is a sensible ceiling.
Python 3 with Pillow and numpy for the token cutout:
<python> -m pip install -r requirements.txt.rembgis optional and adds an AI matte fallback for busy backgrounds (pip install "rembg[cpu]"; first use downloads a ~176 MB model). On Windows, barepythonmay be the Microsoft Store placeholder; setIMAGEGEN_PYTHONin.envto the full path of a realpython.exe.
Install
git clone https://github.com/Txpple/fvtt-mcp-imagegen.git
cd fvtt-mcp-imagegen
npm install
npm run build
cp .env.example .envPut your key in .env:
GEMINI_API_KEY=your-key
IMAGEGEN_OUTPUT_DIR=C:\path\where\renders\should\landThe output folder is created on the first render and must sit outside any git repo. Set
IMAGEGEN_PYTHON too if bare python is not the interpreter you installed the requirements into.
Check the setup from the terminal before registering anything:
npm run doctorIt loads .env the way the server does and runs the same checks as imagegen-status below,
one line each (✓ fine, ! works but worth a look, ✗ broken) with the fix, and exits non-zero
until nothing is broken. The key check is a free model listing; it never renders, so it spends
no credit. Rerun it after each fix.
Register the server with Claude Code (user scope, so it is available in every project), then restart Claude Code:
claude mcp add -s user imagegen -- "C:/Program Files/nodejs/node.exe" /absolute/path/to/fvtt-mcp-imagegen/dist/index.jsGive node as a full path (which node on macOS or Linux): Claude Code launched from the
desktop app may not see it on PATH. A desktop-app install may not put the claude CLI on PATH
either; then add the same entry by hand under mcpServers in ~/.claude.json (user scope) and
restart:
"mcpServers": {
"imagegen": {
"command": "C:/Program Files/nodejs/node.exe",
"args": ["/absolute/path/to/fvtt-mcp-imagegen/dist/index.js"]
}
}.mcp.json.example has the same entry for a project-scoped .mcp.json.
Then ask Claude to run imagegen-status. It is the setup doctor: one line each for the key
(present, and accepted by Google, checked with a free model listing), the output folder
(writable, outside any git repo), and the cutout Python (Pillow, numpy, rembg), each with the
fix when something is wrong (the same checks npm run doctor runs, plus this session's
estimated spend). The server also warns at startup when the key is missing.
Using it
Ask Claude for what you want in table terms:
"Make icons for these six items."
"This goblin needs a token; use my existing orc token as the style reference."
"Illustrate the party arriving at the ruined mill at dusk; here are their portraits."
"Change this token's cloak to forest green."
"This old token looks rough; give it an updated painterly pass."
"Make this bandit token a Sharran cleric: black armour, morningstar, keep the pose."
"These twelve tokens come from three different packs; restyle them all to match this one."
"Illustrate last night's recap; the party's portraits are in this folder."
"Cut the background off this token."
Claude reads every render before showing it to you and fixes obvious flaws (an extra limb, a
duplicated spell effect) with one edit. Files are named <kind>-<slug>-<id>.png (.webp for a map) so they drop
straight into a Foundry asset folder.
With a Foundry MCP server: art grounded in your world
This server only makes pictures. Pair it with a Foundry MCP server such as
fvtt-mcp-dnd5e and Claude can read your
world before it prompts and put the result back when it is done. Then you can ask for things
like:
"Make a new token for the dragon in the Wyrmwood." Claude pulls the actor's stat block and bio, opens the token your world already uses for a similar creature so the angle and line style match, renders, cuts to alpha, and can assign it to the actor.
"Illustrate the party walking into the dragon's lair for the first time." Claude screenshots the battlemap, finds where the dragon's token is placed, reads the plot notes for the room, attaches the party's portraits so the faces hold, and paints the view from the doors down the hall to the dais.
"Illustrate three cool moments from the last few sessions." Claude reads the session recaps and GM notes, picks the scenes, checks which actors were present and what they were carrying that night, and renders each one.
"Give this actor a portrait." Claude reads the bio, looks at the existing token so the hair and skin match canon, renders at 3:4, and can set it as the sheet portrait.
"Icons for every item in this compendium folder." One shared style line, one call per item, uploaded as a set.
The handoff is files on disk: this server writes them, the Foundry server uploads them
(upload-asset, set-actor-art, add-journal-image). Nothing here talks to Foundry directly,
so either half works on its own.
With a campaign repo: the same faces every week
Consistency across a campaign comes from a small file, not from luck. A campaign repo keeps an
art shelf (art/SHELF.md): one approved portrait per player character with the short phrase
that binds it in a prompt ("a bone-white orc in battered steel plate"), two or three finished
pieces that carry the house look, the finish words that keep portraits matte and the palette
muted, and a note of which older files are superseded and must never be attached again. The
illustration-builder skill reads the shelf before every piece, attaches the anchors as
character references and the shelf as style references, and proposes a shelf if the repo has
none yet.
That is how Session Scribe's records stay illustrated by the same people session after session,
how a token redress lands as the actor your world already knows, and how a book assembled at
the end of a campaign reads as one artist's work. Greenrest's shelf, its approved art, and the
chronicle built from them are public in
fvtt-campaign-greenrest.
How it works
Claude ──MCP──> fvtt-mcp-imagegen ──HTTPS──> Gemini image API
│
├── sharp: convert, crop, resize
└── token_cutout.py: chroma key or rembg → alphaThe API returns a JPEG; the server converts to PNG and applies the kind's post-processing (512 square for icons, 16:9 to 16:10 crop for illustrations, cutout for tokens).
Tokens are rendered on a flat chroma plate, then keyed out. Magenta is the default because soft edges keep a trace of the plate and a magenta trace reads as a dark outline on warm subjects (skin, hair, fur, leather) where green reads as an olive fringe; green or blue takes over for purple, pink, or violet subjects. A magenta-composited preview is written beside every cut so the edge can be checked.
Before a token is cut, the server checks the plate's outer edge for subject pixels. A clipped render is redone once and refused if it clips again.
A battlemap is sent padded to the nearest aspect the API renders (a mirrored margin), and the render is mapped back onto the source's pixel grid. The API scales its input to cover the output and trims the excess, so a "3:4" render is 1792×2400, not 1800×2400. Then both images are reduced to edge strength and compared tile by tile (phase correlation): a restyle changes colour and texture, edges stay put. More than 3% of tiles moved by over 0.4% of the long side means the layout drifted. A checkerboard of source and result is written beside every map for the eye.
A render the image safety filter blocks is retried once; the filter is not consistent on the same input.
No local models, no fine-tuning, no ComfyUI. Style comes from reference images you attach.
Development
npm test # offline unit suite; nothing hits the live API
npm run typecheck
npm run check # biome
npm run knip
npm run doctor # the setup checks against your .env (needs a build)npm ci runs two install scripts, both allowed in package.json under allowScripts:
esbuild's (it checks its platform binary; vitest's bundler) and classic-level's (it picks the
prebuilt LevelDB binding; the Foundry CLI behind scripts/unpack_leveldb.mjs). Neither is used
by the server at runtime.
Part of Open Roll 5e
fvtt-mcp-imagegen is one of the three MCP servers in Open Roll 5e, a suite of Foundry VTT modules and Claude Code tooling built for one D&D 5e table and shared. The other servers:
fvtt-mcp-dnd5e: builds D&D 5e content in a live Foundry world from Claude Code: a stat block becomes a complete NPC, a map image a walled and lit scene, an adventure its journals, tables and handouts.
fvtt-mcp-sessionscribe: turns a session's Discord recording and Foundry chat log into its record. Its end-to-end
session-scribeskill drives the server from the Craig link to a speaker-labelled transcript, a fully illustrated player recap, combat statistics, GM notes and a party snapshot.
The modules, each of which installs and works on its own and none of which needs another:
Open Roll 5e: Autoexplore: lets a scene start fully explored, so the whole map shows through the fog of war while tokens still need line of sight.
Open Roll 5e: By the Books: the 2024 rules played from the sheet: a hit rolls and applies its own damage, saves resolve themselves, reactions hold, concentration is tracked, and rests, senses, sizes and lights follow the book. Every rule that rides a use or an effect in the 2024 core books, Heroes of Faerûn, Arcana Unleashed and Ravenloft: The Horrors Within, each step with a receipt and a revert; offered, never enforced.
Open Roll 5e: Combat Plus: automates the chores of running a fight: combat music, an initiative gate, an out-of-turn movement block, defeated marking at 0 HP and turn alerts.
Open Roll 5e: Errata: corrects, in memory, bugs in the premium D&D 2024 books, the dnd5e system and Foundry itself, each fix held until the vendor ships its own.
Open Roll 5e: FX Studio: visual and sound effects for dnd5e, played from what actually happened at the table, with about a thousand stock FX and a window for authoring your own.
Open Roll 5e: Loot Shelf: loot chests and merchant shelves that players can take from, buy from and sell to without owning them, with a receipt for every trade.
Open Roll 5e: Open Server: for hosted worlds: clears the startup pause so players can play before the GM arrives, and gives every user a one-click jump to their character's token, and their familiar's, from the Players list.
Open Roll 5e: Party Stash: makes a dnd5e Group actor's inventory a working party stash: drags move instead of copying, coin moves through a dialog, and every transfer posts a receipt.
Open Roll 5e: Area Sounds: background sound for scenes: random one-shots with silence between them, seamless crossfaded loops, day and night gating, and quiet during combat.
Open Roll 5e: Token Art: gives every token the look of its state, ready, in combat or dead, each a file named beside the base art, with nothing to configure.
Open Roll 5e: Clue Board: keeps the party's Clue Board: every clue the DM hands them, stamped with where it was found and who has read it, pinned to the threads the party names.
Open Roll 5e: Card Catalogue: turns every directory the table uses into a case of cards: the journal, the scenes, the actors, the items and the compendium packs, each found by any word with its main action a click away, and a sidebar that shows only the tabs the table uses.
Open Roll 5e: Crystal Ball: a crystal ball on the sidebar: a player asks a Claude model about the game as their character knows it, the journal they can read, their sheet, their party and its clues, answered by a service beside the server, never from a client.
Issues are welcome on every repo in the family; pull requests are not accepted, since each is one author's design for one table, shared because it might suit yours. How they fit together is mapped in fvtt-suite-openroll5e.
License
MIT. See LICENSE.
Available Tools
4 toolscutout-imageA
Knock the background off a token image to real alpha and deliver it centred on a 512 square so Foundry scale 1.0 is right. Writes a magenta-composited *_preview.png beside it: READ THAT before trusting the edge. Returns coverage, residual-key and haze numbers; a cut that fails any of them falls back to the rembg AI matte automatically.
Inputs: sourceImage (required), size, trim, color, +6 more.
edit-imageA
Edit an existing image with one instruction while keeping identity, pose, angle, and style. Flash for every kind (pro was no better at fixes and re-cropped once). Tokens are prompted light (your instruction as you would type it in the Gemini app, plus a keep-face/hair/angle line and "remove any cast shadow"), put back on a chroma plate keyed to the token's own colours, and cut to alpha on the 512 square in the same call. "give this an updated painterly style" restyles a world token in place; a token from any library or a capture of your own is restyled the same way, its pose and camera kept. Every token and portrait edit is counted by a judge model (heads, eyes, limbs, hands and fingers, tails, tendrils, held objects, and a token's facing) against an optional anatomy line from the book; the result reports anatomy: what it found, each flaw placed in the picture, and for a token the rotation that brings its front to the top. Props (kind "prop") get object-only wording (no figures added) and come back cut at the source file's exact pixel size, ready for the same tile slot. Battlemaps (kind "battlemap") restyle a bought map with the layout locked: the result lands on the source's pixel grid (a whole-number upscale when the source is small), is checked for drift against the source (a drifted render is redone once, then refused), and comes with a checkerboard image of source and result to eyeball. A dressing pass (dressing: true, battlemaps only) adds furniture and props, which the check reads as moved layout, so it renders once and reports drift without retrying or refusing. Overland maps (kind "overland") repaint a regional or world map the same way, painted bare of every name, marker, road, compass rose and scale bar (letter them on afterwards), with a looser drift check that refuses only a grossly moved geography. Returns the new file path, dimensions, and estimated spend.
Inputs: kind (required), slug (required), instruction (required), sourceImage (required), +7 more.
generate-imageA
Generate one Foundry art asset from a prompt via the Gemini image API. kind picks the model tier, aspect, size, framing text, and post-processing; the result is a finished PNG on disk. READ IT before showing anyone: count limbs per creature, check for duplicated spell effects or props, stray signatures, and reference faces on the wrong figure; obvious flaws are one edit-image call away. Every token and portrait render is also counted by a judge model (heads, eyes, limbs, hands and fingers, tails, tendrils, held objects, and a token's facing) against an optional anatomy line from the book; the result reports anatomy. Every kind runs on flash by default; tier: "pro" refuses without confirmPro: true and states the cost. Returns the file path, dimensions, and estimated spend.
Inputs: kind (required), slug (required), prompt (required), tier, +6 more.
imagegen-statusA
Setup doctor and health check: API key present and accepted (no generation credit spent), which image models the key can reach, the output directory (writable, outside any git repo), the cutout Python (Pillow, numpy, rembg), and estimated session spend by tier. Call this first on a cold start.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct role: generate-image creates new assets, edit-image modifies existing assets, cutout-image performs alpha extraction, and imagegen-status checks setup/spend. The generate vs. edit boundary is clear, and cutout/status do not overlap with either. Descriptions reinforce the distinctions with specific use cases.
Three tools follow a clear verb_noun hyphenated pattern: generate-image, edit-image, cutout-image. imagegen-status is the minor deviation, using a noun-style status label rather than verb_noun. Overall the convention is predictable and readable.
Four tools is well-scoped for an image-generation and processing server. Each tool covers a necessary step: create, edit, cut out, and diagnose/status. No tool appears redundant or trivial.
The surface covers the core lifecycle: generate, edit/restyle, cutout, and health/status. Minor gaps exist around asset listing, deletion, batch operations, or variant management, but the main Foundry art workflows are supported. Agents can work around the missing convenience operations.
Maintenance
Related MCP Connectors
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
Roll RPG NPCs (Foundry VTT & SillyTavern V2), import stylized art, MP3 barks & talking MP4s.
Generate logos, social posts, app screenshots, comic panels & visual-novel assets from prompts.
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceIntegrates with FoundryVTT tabletop gaming sessions, allowing AI assistants to query game data, roll dice, generate content (NPCs, loot, encounters), manage combat, and provide tactical suggestions through natural language.6 npm-
- AlicenseNot gradedqualityFmaintenanceEnables AI-powered campaign management for Foundry Virtual Tabletop through natural language, supporting multiple RPG systems with tools for quest creation, character management, combat resolution, and more.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with Foundry Virtual Tabletop, supporting reading world data, managing combat, rolling dice, and updating actor attributes via a sidecar architecture.ISC
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to act as co-GMs and GM assistants within Foundry Virtual Tabletop, providing tools for game mechanics, actors, tokens, combat, canvas placeables, scenes, and world management.MIT