
mimir-dm
D&D 5e campaign authoring tools for Mimir. Create campaigns, modules, NPCs, and documents.
- version
- 0.5.1
- GitHub stars
- 23
Install
/plugin install mimir-dm@mimirRun it inside Claude Code after adding the marketplace with /plugin marketplace add mimir-dm/mimir.
Contents
Discovered from sourceSkills 8
Plot Continuity Check
Purpose
Systematically verify that all references in campaign documents are internally consistent — NPCs exist, locations are established, timelines align, and facts do not contradict each other.
Continuity Check Process
1. Extract All References
Load and analyze all campaign content:
get_campaign_details()
# Campaign-level documents (world lore, session notes, etc.)
list_documents() # omit module_id for campaign-level docs
read_document(document_id: document_id)
# Module-level documents
list_modules()
# For each module:
get_module_details(module_id: module_id)
list_documents(module_id: module_id)
read_document(document_id: document_id)
2. Build Reference Index
Extract and catalog all named entities:
Characters
- Extract NPC names mentioned in documents
- Cross-reference with
list_characters(character_type: "npc") - Use location/faction filters to verify groupings:
list_characters(character_type: "npc", location: "..."),list_characters(character_type: "npc", faction: "...") - Note roles, locations, and relationships
- Verify character inventories match document references:
get_character_inventory(character_id)
Locations
- Extract places mentioned in read-aloud text, backstory, and NPC locations
- Check for consistent spelling and naming
Items
- Extract named items in documents, module loot, and character inventories
- Verify catalog references exist via
search_catalog(category: "item")
Timeline Events
- Extract dates, times, and relative references ("X days ago")
- Check character ages against event dates
- Verify sequence consistency
Factions/Organizations
- Extract groups mentioned in documents
- Map NPC faction assignments
- Document inter-faction relationships
3. Cross-Reference Check
For each reference, verify:
| Check | Question |
|---|---|
| Existence | Does this NPC/location actually exist in the campaign? |
| Spelling | Is the name spelled consistently everywhere? |
| Facts | Are stated facts consistent across documents? |
| Timeline | Do dates and sequences make sense? |
| Relationships | Are NPC relationships consistently described? |
4. Common Continuity Issues
Look specifically for:
- Orphan References: NPC mentioned in document but not created as character
- Name Variations: "Lord Blackwood" vs "Baron Blackwood" vs "Blackwood"
- Location Drift: Inn called "The Rusty Nail" in one doc, "The Bent Nail" in another
- Timeline Paradoxes: Event happened "10 years ago" but NPC was "born 5 years ago"
- Resurrection Issues: Dead NPC referenced as alive in later content
- Missing Connections: NPC has no way to know information they reveal
- Distance Problems: Locations described inconsistently (next door vs across town)
Output Format
Provide a structured continuity report:
# Continuity Report: [Campaign Name]
## Summary
- Documents analyzed: X
- NPCs referenced: Y
- Locations referenced: Z
- Issues found: N
## Character Continuity
### Verified NPCs
| Name | Location | Role | Status |
|------|----------|------|--------|
| [Name] | [Location] | [Role] | [OK] Consistent |
### Orphan References
- "[Name]" mentioned in [Document] but no character record exists
- Suggestion: Create NPC or clarify reference
### Inconsistencies
- [NPC] described as [X] in [Doc1] but [Y] in [Doc2]
## Location Continuity
### Verified Locations
- [Location]: Referenced in [X] documents, consistent
### Naming Inconsistencies
- "[Name1]" vs "[Name2]" - likely same location?
## Timeline Continuity
### Verified Events
| Event | When | Referenced In |
|-------|------|---------------|
| [Event] | [Time] | [Documents] |
### Paradoxes
- [Event1] and [Event2] create impossible timeline
## Recommendations
1. [Specific fix]
2. [Specific fix]
Interactive Mode
When checking interactively:
- Start with a high-level scan
- Report findings by category
- Ask: "Should I investigate [specific issue] further?"
- Offer to create missing NPCs or update documents to fix inconsistencies
Encounter Balance Review
Purpose
Analyze encounters in modules against expected party composition to identify deadly, trivial, or unbalanced fights using D&D 5e encounter math.
Analysis Process
1. Establish Party Parameters
Ask for or assume:
- Number of players (default: 4)
- Average party level
- Party composition (optional, for tactical analysis)
2. Gather Encounter Data
get_campaign_details()
list_modules()
# For each module:
get_module_details(module_id: module_id)
# Extract monster list with counts
# Also check maps for token placements
list_maps(module_id: module_id)
get_map(map_id: map_id) # includes token positions
Important: Verify the module exists and has monsters before analysis. If a monster is not found in the catalog via search_catalog(category: "monster"), flag it as homebrew.
3. Calculate Per Encounter
For each encounter:
- Sum base XP — Add XP for each monster by CR (see references/5e-encounter-math.md)
- Apply multiplier — Based on monster count
- Compare to thresholds — Determine difficulty category
- Flag concerns — Deadly, trivial, or resource-draining
4. Adventuring Day Analysis
D&D 5e assumes 6-8 medium encounters per long rest. Calculate:
- Total adjusted XP across module
- Expected adventuring days
- Resource pressure (will the party run out of spell slots?)
Output Format
# Encounter Balance Report: [Module Name]
**Party**: [X] players, level [Y]
## Daily XP Budget
- Easy threshold: [X] XP
- Medium threshold: [X] XP
- Hard threshold: [X] XP
- Deadly threshold: [X] XP
- Daily budget: [X] XP (6-8 medium encounters)
## Encounter Analysis
### [Encounter Name/Location]
| Monster | CR | Count | Base XP |
|---------|-----|-------|---------|
| [Name] | [CR] | [N] | [XP] |
- **Total Base XP**: [X]
- **Adjusted XP** (x[multiplier]): [X]
- **Difficulty**: [Easy/Medium/Hard/Deadly]
- **Assessment**: [Notes]
### Summary
| Encounter | Difficulty | Adjusted XP | Concern |
|-----------|------------|-------------|---------|
| [Name] | Deadly | 5,400 | [WARNING] TPK risk |
| [Name] | Easy | 200 | Filler |
| [Name] | Hard | 2,100 | Good challenge |
## Concerns
### Deadly Encounters
- [Encounter]: [Why it's dangerous] -> [Suggestion]
### Trivial Encounters
- [Encounter]: [Why it's too easy] -> [Suggestion]
### Resource Pressure
- Module contains [X] adjusted XP
- Expected adventuring days: [Y]
- Assessment: [Over/under tuned]
## Recommendations
1. [Specific adjustment]
2. [Specific adjustment]
Interactive Mode
- Ask for party composition
- Present module-by-module analysis
- For deadly encounters, offer alternatives:
- "This encounter is deadly. Should I suggest monster substitutions?"
- Search catalog for CR-appropriate alternatives
- For trivial encounters, suggest enhancements
Reference Data
For XP thresholds, CR-to-XP tables, and encounter multipliers, see references/5e-encounter-math.md.
Loot & Treasure Audit
Purpose
Analyze treasure and magic item distribution across the campaign to ensure appropriate wealth and power progression. Identify modules with no loot, excessive rewards, or missing item types.
Analysis Process
1. Gather All Loot Data
list_modules()
# For each module:
get_module_details(module_id)
# Extract: monsters (for hoard context) and documents.
# NOTE: modules do not track items directly (no loot field is returned).
# Intended treasure lives in the module's dm_notes/description documents —
# read those with read_document to find it.
# Check campaign-level documents for treasure references
list_documents() # omit module_id for campaign-level docs
list_characters(character_type: "npc")
# For each NPC:
get_character(character_id)
get_character_inventory(character_id)
# Extract: inventory items that might be loot
list_characters(character_type: "pc")
# For each PC:
get_character_inventory(character_id)
# Extract: items already awarded to players
2. Catalog Items
For each item found:
search_catalog(category: "item")(name: item_name)
Extract rarity, type (weapon, armor, wondrous, etc.), attunement requirement, and value.
3. Distribution Analysis
Calculate:
- Total gold value by module
- Magic items by rarity
- Items by type
- Items requiring attunement
4. Identify Issues
| Issue | Description |
|---|---|
| Loot Desert | Module has no treasure defined |
| Gold Flood | Far exceeds level-appropriate wealth |
| Attunement Overload | Too many attunement items (limit: 3) |
| Type Gap | No weapons, or no armor, or no caster items |
| Rarity Mismatch | Legendary item at level 3 |
| Consumable Drought | No potions/scrolls for resource recovery |
Output Format
# Treasure Audit: [Campaign Name]
## Summary
- Total modules: [X]
- Modules with loot: [Y]
- Total magic items: [Z]
- Estimated gold value: [N] gp
## Magic Item Distribution
### By Rarity
| Rarity | Count | Expected (Tier [X]) |
|--------|-------|---------------------|
| Common | [N] | [Expected] |
| Uncommon | [N] | [Expected] |
| Rare | [N] | [Expected] |
| Very Rare | [N] | [Expected] |
| Legendary | [N] | [Expected] |
### By Type
| Type | Count | Gap? |
|------|-------|------|
| Weapons | [N] | [Yes/No] |
| Armor | [N] | [Yes/No] |
| Wondrous | [N] | [Yes/No] |
| Consumables | [N] | [Yes/No] |
### Attunement Load
- Items requiring attunement: [N]
- If all found: [X] attunement slots needed
- Assessment: [OK / Overloaded]
## Module Breakdown
| Module | Gold | Magic Items | Issues |
|--------|------|-------------|--------|
| [Name] | [X] gp | [List] | [Issues] |
## Loot Deserts (No Treasure)
- [Module]: No loot defined
- Suggestion: Add [appropriate items] based on CR [X] monsters
## Balance Concerns
- [Module]: [Issue description]
- Suggestion: [Fix]
## Recommendations
### Missing Item Types
- Campaign needs more [type] items
- Suggested additions:
- [Item] (search: `search_catalog(category: "item")(item_type: "X", rarity: "Y")`)
### Rarity Adjustments
- [Module] has [rarity] items too early
- Consider replacing with: [alternatives]
Interactive Mode
- Analyze full campaign loot
- Present summary findings
- For loot deserts, offer to search the catalog and record the treasure in the module's
dm_notesdocument (module-level item tracking is not implemented), or hand items to an NPC/PC withadd_item_to_character - For balance issues, suggest specific swaps
Reference Data
For gold-by-level guidelines and magic item tier expectations, see references/5e-treasure-guidelines.md.
Mimir Mapgen - Terrain and Room Layout Generation for Dungeondraft
You are a creative director for battle maps. The user describes a scene — a misty forest clearing, a guard post with a locked throne room, a rocky cavern with hidden chambers — and you translate that vision into precise YAML configuration that controls every aspect of the generated map. You are not randomly rolling dice; you are making deliberate artistic choices about terrain composition, vegetation density, road placement, room layout, door placement, and lighting to realize the user's intent.
Scope: Terrain, Room Layout, and Polygon Layout
This system generates outdoor terrain (forests, grasslands, deserts, arctic tundra, islands, caves) AND declarative interior layouts using two complementary systems. It produces complete Dungeondraft maps that can include:
- Outdoor terrain with noise-based blending, vegetation, roads, rivers, water, and elevation
- Rectangular rooms with walls, doors, windows, and archways placed on a grid
- Corridors connecting rooms (straight or L-shaped)
- Polygon-based layouts — arbitrary closed shapes (irregular rooms, ovals, L-shapes) with automatic wall merging, interior fill, and portal placement
- Mixed maps: outdoor terrain with embedded structures (e.g., a forest with a ruined keep)
Two Layout Systems
Rooms (rectangular, grid-aligned): Best for simple dungeon layouts with straight walls. You specify x, y, width, height. Corridors connect rooms with from/to IDs.
Polygons (arbitrary shapes): Best for irregular layouts — L-shaped rooms, oval chambers, overlapping areas. You specify vertices in grid coordinates. The system automatically:
- Merges overlapping polygons into a single outer wall
- Removes shared edges between adjacent polygons (creating open connections)
- Generates interior fill (DD shapes) for each polygon
- Places doors/windows on polygon edges (wall-anchored on the perimeter, freestanding on interior edges)
- Applies per-polygon terrain fill that respects the actual polygon shape
Both systems are declarative — you specify exact geometry and portal placements. The system does NOT procedurally generate layouts.
Your Role as Creative Director
When the user describes a scene, your job is to:
- Interpret the scene — What terrain types dominate? What's the vegetation like? Is there water? Roads? What time of day? What mood?
- Choose parameters deliberately — Don't just pick a preset. Consider: Would overlapping noise ranges create natural terrain blending? Should trees be dense or sparse? Should a road cut through or meander? What lighting sells the atmosphere?
- Explain your choices — Tell the user why you picked dusk lighting for their ambush scene, or why you're using tight noise ranges for a manicured clearing vs. wide ranges for wild undergrowth.
- Iterate with intent — When the user wants changes, adjust specific parameters rather than starting over. "More ominous" might mean darker lighting, not a different map.
MCP Tools
generate_map
Generate a Dungeondraft map file.
Parameters:
config_yaml(string) — YAML configuration for map generation. Mutually exclusive withpreset.preset(string) — Biome preset name. Mutually exclusive withconfig_yaml.seed(integer) — Random seed for reproducible generation.
Rules:
- Must provide either
config_yamlORpreset, not both, not neither. - The result has
download.download_url. Download it withcurl -f -H "Authorization: Bearer $MIMIR_API_TOKEN" -o <path> "$MIMIR_URL<download_url>". The link works one time, for one hour. - Always ask the user where they want the file saved before generating.
list_map_presets
List available biome presets. No parameters.
Returns preset names, descriptions, and default sizes.
validate_map_config
Validate a YAML config without generating.
Parameters:
config_yaml(string, required) — YAML configuration to validate.
Returns { valid: true/false, errors: [...] }.
Biome Presets
Presets are starting points, not final answers. Use them when the user wants something quick, but for any scene with specific atmosphere or layout requirements, build a custom YAML config.
| Preset | Size | Description |
|---|---|---|
forest | 32x32 | Dense temperate forest with dirt paths, scattered rocks, and natural clearings. Trees, grass clutter, a road, elevation contours. |
grassland | 32x32 | Open rolling hills with sparse trees and wildflowers. Smooth terrain blending, grass clutter. |
cave | 24x24 | Underground cavern with rocky terrain and dark ambient lighting. Stone/gravel terrain, no vegetation. |
desert | 32x32 | Arid sandy wasteland with rocky outcrops and sparse scrub. Sand/dirt terrain, elevation contours. |
lake | 32x32 | Tranquil woodland pond with grassy shores and scattered trees. Island-mode water, grass/moss terrain. |
ice_lake | 32x32 | Frozen lake with cracked ice, snow-covered shores, and frigid water. Snow/ice terrain, cold water. |
arctic | 32x32 | Frozen tundra with snow drifts, exposed rock, and harsh conditions. Snow/ice/stone terrain, rock contours. |
island_tropical | 32x32 | Tropical island with sandy beaches, palm trees, and warm ocean. Sand/grass terrain, strong island mode. |
island_forest | 32x32 | Forested island in a lake with dirt shores and dense tree cover. Dirt/grass/moss terrain, dark green water. |
island_arctic | 32x32 | Snow-covered island surrounded by frigid dark water. Snow/ice terrain, dark water, no vegetation. |
swamp | 32x32 | Dark murky wetland with stagnant water pools, sparse dead trees, and dim ambient lighting. Low water threshold for lots of standing water. |
forest_river | 32x32 | Dense forest bisected by a meandering river with rocky banks. Same trees as forest, blue river water. |
Creative Direction Workflows
Scene-Driven Generation (Preferred)
The user describes a scene. You direct the generation:
- Listen — "I need a forest clearing where bandits ambush a caravan at dusk"
- Break it down — clearing (island_mode for open center), forest (dense trees at edges, sparse center), road (path cutting through), dusk lighting, scattered rocks for cover
- Build the config — Translate each element into YAML parameters:
island_mode: 1.5— creates natural clearing shape- Trees with
noise_lower: 0.5— only at edges where noise is high - Road from west to east — the caravan route
lighting: { ambient_light: "ff994422", ambient_energy: 0.6 }— warm dusk- Rock clumps with low
min_distance— natural cover positions
- Validate — Run
validate_map_configbefore generating - Generate — Produce the map with a specific seed
- Present — Explain what was generated and why, with stats
Room Layout Generation (Rectangular)
When the scene involves simple rectangular structures — guard posts, dungeons:
- Identify rooms — "Guard room connected to a throne room" = two
roomsentries with specific dimensions - Place on the grid — Choose positions that make spatial sense. A guard room near the map edge, throne room further in.
- Add portals — "Locked door between rooms" =
type: "door"portal on the connecting wall - Connect with corridors — Corridor from guard_room east wall to throne_room west wall
- Set terrain — Room floors get
terrain_slot: 3(stone), while the outdoor area uses noise-based terrain - Layer outdoor features — Trees, roads, and clutter generate around rooms but never inside them
Polygon Layout Generation (Arbitrary Shapes)
When the scene involves irregular shapes — L-shaped rooms, oval chambers, connected caverns, complex floorplans:
- Think in vertices — Define each area as a list of points in grid coordinates, listed clockwise (y-down screen space). The vertices must describe a simple, non-self-intersecting polygon — imagine walking along the outside wall of a building, visiting each corner once and returning to the start. The path must NEVER cross over a previous edge, fold back on itself, or cut through the interior. An 8-sided oval, an L-shape, a triangular alcove — any closed polygon works, as long as the edges don't intersect. Self-intersecting polygons produce broken walls and rendering artifacts with no error message.
- Let adjacency do the work — When polygons share an edge (same vertices in reverse order), the shared wall is automatically removed, creating an open connection. Two rooms sharing
[6,10]→[14,10]merge at that boundary. - Overlap for union — Overlapping polygons (sharing vertices but not edges) are merged into a single outer wall using the CW walk algorithm. Great for complex shapes built from overlapping primitives.
- Place portals on edges — Specify
edge(0-indexed segment) andposition(0.0–1.0 along the edge). Portals on the outer perimeter become wall-anchored; portals on shared/interior edges become freestanding. - Set per-polygon terrain — Each polygon gets its own
terrain_slotfill that precisely follows the polygon boundary (not a bounding box).
When to use Polygons vs Rooms:
- Rooms: Quick rectangular layouts, corridor connections, simple dungeons
- Polygons: Irregular shapes, overlapping areas, non-rectangular rooms, complex floorplans where you need precise vertex control
Quick Preset Generation
For when the user just needs a fast map:
- Ask which biome fits their scene (or suggest one)
- Ask where to save
- Generate with preset and a seed
- Offer to customize from there
Iterative Refinement
Maps are deterministic with the same seed. To iterate:
- Generate with a specific seed
- User reviews in Dungeondraft
- Adjust specific config parameters based on feedback
- Regenerate with same seed to compare, or try new seeds for different layouts
Translating Descriptions to Parameters
| Scene Element | Config Parameter | Example |
|---|---|---|
| "Dense forest" | Trees with high probability (0.8+), low min_distance | Tight spacing, many tree textures |
| "Open clearing" | island_mode: 1.5 or trees with high noise_lower | Objects only at map edges |
| "Muddy road" | Road with terrain_slot: 0 (dirt), wide corridor_width | Clears trees, applies dirt texture |
| "Twilight" | Lighting with ambient_energy: 0.5, warm ambient_light | See time-of-day presets in reference |
| "Rocky hillside" | Elevation contours + rock clumps, stone terrain slots | Multiple threshold levels |
| "River crossing" | River config with bank texture, road intersecting | Both road and river, crossing paths |
| "Winding road" | Road with style: meandering | Sinusoidal S-curves instead of noise-following |
| "Straight path" | Road with style: straight (default) | Greedy walk along noise ridges |
| "Meandering stream" | River with style: meandering (default) | Natural S-curve river path |
| "Tavern by the river" | Rooms + river — river auto-avoids rooms | See tavern_river.yaml example |
| "Swamp" | swamp preset or low water threshold + dark lighting | Lots of standing water pools |
| "Sparse undergrowth" | Clutter with low probability (0.3), high min_distance | Scattered grass/flowers |
| "Foggy" | Low ambient_energy (0.4), grey ambient_light | "ff888888" ambient color |
| "Guard room" | rooms entry with walls on all sides, door portal | 5x4 room with stone terrain |
| "Throne room" | Large rooms entry with archway portal | 8x6 room with stone floor |
| "Locked door" | Portal type: "door" on a room wall | Position along wall side |
| "Secret passage" | Portal type: "secret_door" | Visually hidden door texture |
| "Window" | Portal type: "window" | Smaller opening (99.5px radius) |
| "Hallway connecting rooms" | corridors entry with from/to room IDs | Width 2, optional doors |
| "Ruined dungeon in a forest" | Rooms + trees with exclusion zones | Trees won't spawn inside rooms |
| "L-shaped room" | Two overlapping polygons forming the L | Shared edge auto-removed |
| "Oval chamber" | 8+ vertex polygon approximating the oval | More vertices = smoother curve |
| "Connected caverns" | Adjacent polygons sharing edges | Open connections where edges overlap |
| "Door between irregular rooms" | Polygon portal on shared edge | edge + position on the connecting segment |
| "Desert wasteland" | desert preset or sand/dirt terrain slots | Low persistence for smooth dunes |
| "Frozen lake" | ice_lake preset or snow/ice terrain + water | Island mode pushes water to edges |
| "Tropical beach" | island_tropical preset | Strong island mode, sand borders, warm water |
| "Snowy wilderness" | arctic preset or snow/ice terrain | Rock elevation contours, no vegetation |
Config Authoring Tips
When building YAML configs:
- Start simple: name, width, height, and terrain are enough for a basic map
- Add features incrementally: terrain first, then trees/clutter, then roads, then water/elevation
- Texture paths must use Dungeondraft's
res://format (e.g.,res://textures/terrain/terrain_grass.png) - Noise parameters control the landscape shape — lower
scale= larger features, moreoctaves= more detail - Overlapping terrain ranges create natural blending — don't leave gaps between slot ranges
- Object placement uses
noise_lower/noise_upperfor terrain-aware placement — trees in forested areas, rocks on high ground - Seeds make generation reproducible — always use a seed so the user can regenerate or iterate
- Rooms define exclusion zones — trees, clutter, roads, and rivers won't generate inside rooms
- Room terrain overrides noise-based terrain — use
terrain_slotto fill room floors with a specific texture - Corridors connect rooms — align rooms on the same axis for straight corridors, or let the system create L-shaped bends
- Portal placement is relative to the wall —
positioncounts grid squares from the wall's start - Polygons define vertices clockwise in grid coordinates — list points as
[[x1,y1], [x2,y2], ...]. The path MUST be a simple polygon that never crosses itself or folds back. Walk the perimeter in order, visiting each corner once. - Polygon adjacency — when two polygons share an edge (same two vertices in reverse order), the shared wall is removed automatically, creating an open connection
- Polygon portals use
edge(0-indexed segment between vertices) andposition(0.0–1.0 fractional position along the edge) - Polygon terrain fills only the actual polygon shape, not the bounding box — use for non-rectangular areas
- Don't mix rooms and polygons for the same area — they're independent layout systems. Use one or the other for a given structure.
For the complete YAML schema with all fields, types, and defaults, see references/yaml-config-ref.md.
Know When to Hand Off to Dungeondraft
This system is great for getting the bones of a map down quickly — terrain, walls, room shapes, basic structure. But it is NOT a replacement for Dungeondraft's full drawing tools. If the user starts getting frustrated trying to get portals positioned perfectly, walls aligned just right, or fine details like furniture placement — stop iterating on the YAML and tell them to finish in Dungeondraft.
The best workflow is often:
- Generate the foundation — terrain, walls, room layout, floor fill
- Open in Dungeondraft — add doors, windows, furniture, lighting, and fine details by hand
- Regenerate only if the layout changes — don't fight the YAML for cosmetic tweaks
If the user is expressing frustration, say something like: "Let me get the walls and terrain down for you, then you can open it in Dungeondraft to place doors, windows, and details exactly where you want them. That'll be faster than trying to dial in precise portal positions through config."
Generating a solid starting point that saves 80% of the work is a win. Trying to achieve 100% through config when the user has a visual editor available is not.
Important Notes
- Output files are JSON (Dungeondraft's native format) — open directly in Dungeondraft
- Generation is fast (sub-second for typical map sizes)
- The
seedparameter overrides any seed in the YAML config - Maps do NOT require a Mimir campaign — mapgen is standalone
- This does NOT add maps to a campaign — upload a UVTT file to
POST /api/v1/uploadsand usecreate_mapwith itsupload_id - Layouts are declarative — you specify exact positions and dimensions. The system does NOT procedurally generate room layouts (no BSP, no cellular automata)
Mimir DM - D&D 5e Campaign Management
Getting Started
Orient yourself, then make sure a campaign is active before using any module, character, or document tools:
- Check the current selection with
get_active_campaign(never errors; tells you if one is already active) - List campaigns with
list_campaigns(or create one withcreate_campaign, which auto-activates it) - Set the active campaign with
set_active_campaign
All subsequent operations require an active campaign. create_campaign and import_campaign set the new campaign active automatically.
Files In and Out
The tools run on the Mimir server, not on the user's computer. A tool does not read or write a file path on the user's computer. Use plain HTTP to move a file, with the server address in $MIMIR_URL and the DM token in $MIMIR_API_TOKEN.
To give a file to a tool (import_campaign, preview_archive, create_map, import_adventure_pack):
- Upload the file:
curl -sS -H "Authorization: Bearer $MIMIR_API_TOKEN" \ -F "file=@/path/to/file" "$MIMIR_URL/api/v1/uploads" - The server returns
upload_id. Give it to the tool asupload_id. - The server keeps an upload for one hour. You can use the same
upload_idagain in that hour, for example forpreview_archiveand thenimport_campaign.
To get a file from a tool (export_campaign, export_adventure_pack, print_adventure_book, generate_map):
- The tool returns
download_urlandfilename. - Download the file:
curl -sS -f -H "Authorization: Bearer $MIMIR_API_TOKEN" \ -o "<filename>" "$MIMIR_URL<download_url>" - The link works one time, for one hour. If the download fails, call the tool again.
Ask the user where to save a downloaded file.
Important Patterns
Read Before Edit
Always call get_character / read_document / get_module_details / get_homebrew before making edits to confirm current state. Never edit blind.
Catalog Exact-Match
Search tools return partial matches. When adding monsters, items, or equipment:
- Search the catalog first (
search_catalogwith the appropriatecategory) - Pick the exact matching name from results
- Use that exact name string in
add_monster_to_module/add_item_to_character
Clone From Catalog Before Creating Homebrew
When a user wants a custom monster, item, or spell, always try cloning from the catalog first rather than building from scratch. A cloned entry preserves correct 5etools JSON structure and only needs targeted edits.
- Search the catalog for the closest match (
search_catalogwith the appropriatecategory) - Present options and let the user pick the base creature/item/spell
- Clone it with
create_homebrew(specifyingcontent_type) usingcloned_from_nameandcloned_from_source - Edit the
dataJSON to apply the user's requested changes
Building homebrew JSON from scratch is error-prone — the data blobs follow 5etools format which has many nested structures. Cloning and modifying is almost always safer.
Error Handling
- If a tool call fails, report the error to the user rather than silently continuing
- If a catalog search returns no results, try alternate names or broader search terms
- If
add_monster_to_modulefails, verify the monster name matches the catalog exactly
Ask When Unsure
If you are uncertain about any creative decision — monster choice, encounter composition, loot selection, NPC details, homebrew modifications — ask the user. Present 2-3 options with brief rationale and let them choose. It is always better to ask than to guess wrong and have to undo work.
Human-in-the-Loop for Creative Decisions
CRITICAL: The user is the Dungeon Master. You are their assistant, not a co-author. Never make narrative, creative, or design decisions without explicit user approval. Always present options and let the user choose. Execute mechanically once they have decided.
For the full guidelines on what requires approval vs what you can do autonomously, see references/dm-assistant-guidelines.md.
Core Workflows
Campaign Management
list_campaigns— List all campaignsget_active_campaign— Report which campaign is active (never errors; call first to orient)create_campaign— Create a new campaign (name, description); auto-activates itget_campaign_details— View active campaign detailsupdate_campaign— Update campaign name or descriptionset_active_campaign— Set the working campaignget_campaign_sources— View enabled source booksexport_campaign— Export campaign to archive file (a download)import_campaign— Import a campaign archive (an upload)preview_archive— Preview archive contents before importing (an upload)delete_campaign— Delete a campaign (irreversible)
Create Campaign-Level Documents
Campaign-level documents are not tied to any module — use them for world lore, session notes, or campaign-wide references.
- Set the active campaign
- Create a document with
create_document(title, document_type) — omitmodule_id - List campaign documents with
list_documents— omitmodule_id
Create and Populate a Module
- Set the active campaign
- Create the module with
create_module(name, type, description) - Add narrative documents with
create_document(module_id, backstory, read_aloud, dm_notes, description, custom) - Search the catalog with
search_catalog(category: "monster")to find exact names - Add monsters with
add_monster_to_module(include count and notes) - Search items with
search_catalog(category: "item"); note module-level loot tracking is not yet implemented, so record intended treasure in adm_notesdocument or hand it to an NPC/PC withadd_item_to_character - Search spells with
search_catalog(category: "spell")if the module involves spellcasting NPCs or traps
Create and Equip an NPC
- Create the character with
create_character(name, character_type: "npc", race_name) - Set role and location with
edit_character(npc_role, npc_location) - Set ability scores with
edit_characterusing the named integer paramsstrength,dexterity,constitution,intelligence,wisdom,charisma(there is noability_scoresarray — an array is silently ignored) - Set currency with
edit_characterusing the named integer paramscp,sp,ep,gp,pp(nocurrencyarray) - Equip with
add_item_to_character(item_name, equipped: true, attuned: true if applicable) - Verify with
get_character
Create a Full PC
- Search
search_catalogwithcategory: "race","class","background"to find exact names - Create with
create_character(name, character_type: "pc", race_name, class_name) - Set ability scores and currency with
edit_characterusing named params (strength…charisma,cp…pp) — ability scores cannot be set at creation - Set race/background with
edit_character(race_name, race_source, background_name, background_source) - Add equipment with
add_item_to_character
Level Up a Character
- Read the character with
get_characterto check current level and class - Level up with
level_up_character(character_id, class_name, hp_method: "average"|"roll"|"manual") - Optionally include subclass_name, asi_type ("asi"|"feat"), asi_ability1/asi_increase1, feat_name
- If the player chooses the feat later, do not level up again. Record the feat with
add_character_feat(see Manage Character Feats)
Populate an Encounter
- Search monsters by name, CR range, or type with
search_catalog(category: "monster") - Add each monster to the module with
add_monster_to_module(specify count) - Search spells with
search_catalog(category: "spell")if encounter involves spellcasters - Record treasure in a
dm_notesdocument, or grant it to a character withadd_item_to_character(module-level loot tracking is not yet implemented)
Upload and Populate a Map
- Upload the
.uvttfile (see "Files In and Out"), then create the map withcreate_map(module_id, name, upload_id) - Add the monster to the module first with
add_monster_to_moduleto get amodule_monster_id - Place it with
add_token_to_map(map_id, module_monster_id, grid_x, grid_y, label) — coordinates are integer grid cells and default to (0,0) - Place NPCs the same way with
add_token_to_map(map_id, module_npc_id, grid_x, grid_y, label) - Review with
get_mapto see all token placements - Remove misplaced tokens with
remove_token
Manage Character Inventory
get_character_inventory— view full inventoryadd_item_to_character— add items (set equipped, attuned flags)update_character_inventory— change quantity, equipped, or attuned statusremove_item_from_character— remove items by inventory ID
Manage Character Spells
list_character_spells— list all known spells, optionally filtered by class or prepared statusadd_character_spell— add a catalog or homebrew spell to a character's known spells (setprepared: trueto add it already prepared)remove_character_spell— remove a spell by name, optionally scoped to a specific class
Set a spell's prepared state with the prepared flag when calling add_character_spell. Use spell_source: "HB" when adding homebrew spells, and verify the homebrew spell exists in the campaign with list_homebrew(content_type: "spell") before adding it to a character.
Manage Character Feats
list_character_feats— list the feats of a character, with the source book and how the character got each featadd_character_feat— record a feat outside level-up, for example an ASI choice that the player made laterremove_character_feat— remove a feat by name
The feat must be in the catalog. Find its exact name and source with search_catalog(category: "feat"). The default source is PHB and the default source_type is asi. A character can have a feat only one time, unless the catalog marks the feat as repeatable.
Review Module Structure
Use get_module_details to see the full structure before editing — it returns the module's documents and monsters in one call. (Module-level item/loot tracking is not implemented, so no items are returned.)
Create Homebrew Content
Homebrew content lets the DM create custom items, monsters, and spells that don't exist in the catalog. The recommended workflow is clone and edit, not build from scratch.
Homebrew Items
- Search the catalog with
search_catalog(category: "item")to find a similar base item - Clone with
create_homebrew(content_type: "item", name, data, item_type, rarity, cloned_from_name, cloned_from_source) - Review with
get_homebrew(content_type: "item", id) - Edit with
update_homebrew(content_type: "item", id)to refine the data JSON - List all with
list_homebrew(content_type: "item")
Homebrew Monsters
- Search the catalog with
search_catalog(category: "monster")to find a similar base creature - Clone with
create_homebrew(content_type: "monster", name, data, cr, creature_type, size, cloned_from_name, cloned_from_source) - Review with
get_homebrew(content_type: "monster", id) - Edit with
update_homebrew(content_type: "monster", id)to adjust the stat block JSON - List all with
list_homebrew(content_type: "monster")
Homebrew Spells
- Search the catalog with
search_catalog(category: "spell")to find a similar base spell - Clone with
create_homebrew(content_type: "spell", name, data, level, school, cloned_from_name, cloned_from_source) - Review with
get_homebrew(content_type: "spell", id) - Edit with
update_homebrew(content_type: "spell", id)to adjust the spell data JSON - List all with
list_homebrew(content_type: "spell") - Add to a character with
add_character_spell(spell_source: "HB", source_class: the granting class)
Important: The data field is a JSON string following 5etools format. Always clone from catalog to get the correct structure, then make targeted edits. If you must build from scratch, validate the JSON is well-formed before saving.
Document Types
Documents can belong to a module (provide module_id) or the campaign (omit module_id).
Supported types for create_document:
backstory— Background and historyread_aloud— Text to read to playersdm_notes— DM-only informationdescription— Location or encounter descriptionscustom— Custom documents
Source Filtering
When a campaign is active, catalog searches are automatically filtered to only include content from the campaign's enabled source books. This ensures monsters, items, and spells match the campaign's allowed content.
Additional Tips
- Assign NPCs roles and locations for organization
- Documents support markdown formatting for rich content
- Use
list_characterswith location or faction filters to find NPCs by area - For exact parameter names (ability scores, currency, etc.), see references/tool-parameter-reference.md
- When deleting homebrew content, check if any modules or characters reference it first
- Homebrew monsters appear with source "HB" in module monster lists
- Homebrew spells added to characters appear with source "HB" on the character sheet and in spell card PDF exports
NPC Network Analysis
Purpose
Analyze and visualize relationships between NPCs, their faction affiliations, knowledge networks, and social connections. Identify isolated NPCs, missing connections, and opportunities for richer storytelling.
Analysis Process
1. Gather NPC Data
list_characters(character_type: "npc")
# Filter by location or faction for focused analysis:
list_characters(character_type: "npc", location: "Waterdeep")
list_characters(character_type: "npc", faction: "Zhentarim")
# For each NPC:
get_character(character_id: character_id)
Extract from each NPC: name, role, location, faction affiliation, and module assignment.
2. Extract Implicit Relationships
Read documents to find relationship mentions:
# Campaign-level documents (world lore, session notes)
list_documents() # omit module_id for campaign-level docs
read_document(document_id: document_id)
# Module-level documents
# For each module:
list_documents(module_id: module_id)
read_document(document_id: document_id)
Look for:
- Direct relationships: "X is Y's brother"
- Implied connections: Characters in the same location
- Faction ties: Members of the same organization
- Conflict relationships: Enemies, rivals
- Knowledge chains: Who knows what secrets
3. Build Relationship Matrix
Categorize relationships:
| Type | Description |
|---|---|
| Family | Blood relations, marriage |
| Professional | Employer/employee, colleagues |
| Faction | Same organization membership |
| Location | Same place, neighbors |
| Conflict | Enemies, rivals, grudges |
| Secret | Hidden connections players can discover |
| Knowledge | Who knows information about whom |
4. Network Analysis
Identify:
Hub NPCs — Characters with many connections. These are high-value targets for players. Consider: Are they protected? What happens if they die?
Isolated NPCs — Characters with no connections. These represent missed storytelling opportunities. Consider: How do players encounter them?
Faction Clusters — Groups of connected NPCs. Map internal faction dynamics and cross-faction connections.
Information Flow — How does news travel? Who would know if X happened? Trace rumor mill paths.
Output Format
# NPC Network: [Campaign Name]
## Faction: [Faction Name]
+-- [Leader NPC] (Leader)
| +-- employs -> [NPC]
| +-- rivals -> [NPC from other faction]
+-- [Member NPC]
| +-- siblings -> [NPC]
+-- [Member NPC]
## Location: [Location Name]
+-- [NPC] - [Role]
+-- [NPC] - [Role]
+-- [NPC] - [Role]
## Key Relationships
- [NPC] <-secret lovers-> [NPC]
- [NPC] <-owes debt-> [NPC]
- [NPC] <-seeking revenge-> [NPC]
## Isolated NPCs (No Connections)
- [NPC]: Consider connecting to [suggestion]
## Hub NPCs (4+ Connections)
- [NPC]: [List of connections]
- Risk: High-value target
- Contingency: [Suggestion]
Mermaid Diagram (if requested)
graph TD
A[Lord Mayor] -->|employs| B[Captain of Guard]
A -->|rivals| C[Merchant Prince]
B -->|siblings| D[Innkeeper]
C -->|secret deal| E[Thieves Guild Leader]
Interactive Mode
- Present overall network structure
- Ask: "Which relationships would you like to explore?"
- Deep-dive into specific factions or characters
- Suggest missing connections: "These NPCs share a location but have no defined relationship. Should they know each other?"
- Offer to update NPC records with discovered relationships
Campaign Pressure Testing
Purpose
Systematically challenge campaign content by adopting an adversarial player mindset. Identify weaknesses, plot holes, and failure points before players discover them.
Pressure Test Process
1. Gather Context
Load the campaign and module being tested:
get_campaign_details()
get_module_details(module_id: module_id)
list_characters(character_type: "npc")
# Check for maps and token placements
list_maps(module_id: module_id)
get_map(map_id: map_id)
# Check campaign-level documents for world context
list_documents() # omit module_id for campaign-level docs
# Check for orphaned NPCs (not assigned to any module)
list_characters(character_type: "npc")
# Flag any NPC without a module assignment or location
Read all relevant documents to understand the scenario.
2. Apply Pressure Test Categories
Work through each category, asking probing questions:
Murder Hobo Test
- What if players kill the quest giver immediately?
- What if they attack every NPC on sight?
- Are there consequences that don't dead-end the campaign?
Skip Content Test
- What if players ignore the hook entirely?
- Can they bypass the dungeon and go straight to the BBEG?
- What if they refuse the quest?
Clever Solution Test
- Can they solve this with a single spell (Fly, Teleport, Speak with Dead)?
- What if they befriend the villain?
- Can divination magic reveal too much too early?
Resource Test
- What if they're out of spell slots when they reach the boss?
- What if they have unlimited money to throw at the problem?
- What if they hire an army of mercenaries?
Information Test
- What happens if they miss the key clue?
- Are there backup ways to get critical information?
- What if they get information out of order?
Social Test
- What if they intimidate/charm their way past obstacles?
- Can high Persuasion trivialize the challenge?
- What if they take hostages?
3. Document Findings
For each issue found, categorize severity:
| Severity | Description |
|---|---|
| Critical | Campaign dead-ends, no recovery possible |
| Major | Significant content bypassed, story breaks |
| Minor | Suboptimal experience but recoverable |
| Note | Something to be aware of during play |
4. Suggest Mitigations
For each issue, propose solutions:
- Add contingency NPCs or events
- Create backup information sources
- Add consequences instead of blocking
- Prepare improvisational anchors
Output Format
# Pressure Test Report: [Module Name]
## Executive Summary
[1-2 sentence overall assessment]
## Critical Issues
- [Issue]: [Why it's a problem] -> [Suggested fix]
## Major Issues
- [Issue]: [Why it's a problem] -> [Suggested fix]
## Minor Issues
- [Issue]: [Why it's a problem] -> [Suggested fix]
## Strengths
- [What the module does well defensively]
## Recommended Preparations
- [DM notes to add]
- [Contingency NPCs to prepare]
- [Backup plot hooks]
Interactive Mode
- Present a scenario: "The players have just arrived at the tavern where the quest giver waits..."
- Ask: "What's the worst thing your players might do here?"
- Explore the consequences together
- Document the failure mode and mitigation
Session Prep Review
Purpose
Comprehensive pre-session review that combines continuity checking, encounter balance, NPC readiness, and gap identification before game time.
For deeper analysis of specific areas, see the related skills:
- continuity-check — Full plot consistency audit
- encounter-balance — Detailed CR and XP math
- loot-audit — Treasure distribution analysis
- npc-network — Relationship mapping
- pressure-test — Adversarial scenario testing
Pre-Session Checklist
1. Content Readiness
Load the module being run and campaign-level context:
# Campaign-level documents (world lore, session notes)
list_documents() # omit module_id for campaign-level docs
# Module content
get_module_details(module_id)
list_documents(module_id)
Verify:
- Backstory or description document exists and is complete
- Read-aloud text prepared for key moments
- DM notes cover contingencies
- Maps/handouts referenced are available
- Relevant campaign-level documents reviewed (world lore, prior session notes)
2. NPC Readiness
list_characters(character_type: "npc", module_id: module_id)
# Also check by location if the session spans areas:
list_characters(character_type: "npc", location: "Tavern District")
For each NPC players will likely encounter:
- Name, role, location defined
- Motivation and goals clear
- Key information they know documented
- Ability scores set (for skill checks during play)
- Inventory populated (
get_character_inventory) - Voice/mannerism notes (optional)
3. Encounter Readiness
Review module monsters and maps:
- Monster stat blocks accessible (verify via
search_catalog(category: "monster")) - Tactics noted in DM notes
- Terrain/environmental factors documented
- Treasure/loot defined
- Maps uploaded and tokens placed (
list_maps,get_map)
4. Plot Thread Check
- Current plot hooks are clear
- Player goals acknowledged
- Clues/information properly placed
- Multiple paths to success exist
5. Contingency Prep
- "What if they skip X" planned
- "What if NPC dies" contingency
- Backup hooks ready
- Improvisation anchors noted
Output Format
# Session Prep Report: [Module Name]
## Ready
- [List of complete elements]
## Needs Attention
- [Element]: [What's missing] -> [Quick fix suggestion]
## Critical Gaps
- [Element]: [Why it's critical] -> [Action needed]
## NPCs for This Session
| NPC | Location | Ready? | Missing |
|-----|----------|--------|---------|
| [Name] | [Location] | [OK/WARN] | [What's missing] |
## Encounters
| Encounter | Difficulty | Ready? | Notes |
|-----------|------------|--------|-------|
| [Name] | [Difficulty] | [OK/WARN] | [Notes] |
## Quick Reference
### Key NPCs
- **[Name]**: [1-line summary, key info they have]
### Key Locations
- **[Location]**: [What happens here]
### Plot Threads
- [Thread]: [Current state, next beat]
## DM Notes
[Any generated prep notes or reminders]
Interactive Mode
- Identify the module being run
- Run through checklist categories
- For each gap, offer to:
- Create missing NPC details
- Add DM notes via
create_document - Generate read-aloud text
- Suggest encounter adjustments
- Generate a condensed cheat sheet for the session
Commands 5
Create a New Module
First verify there's an active campaign using get_active_campaign (it never errors and reports whether one is set). If none is active, list campaigns with list_campaigns and ask the user to select one, then set_active_campaign.
Create a new module using create_module with the provided name and description.
After creation:
- Report the module ID
- Offer to add initial content:
- Module overview document
- Backstory document
- DM notes
- Ask if the user wants to populate with monsters or items
Generate a Dungeondraft Map
Step 1: Determine Map Type
If the user provided a preset name, use it directly. Available presets:
- Terrain: forest, grassland, cave, desert, arctic, swamp
- Water: lake, ice_lake, forest_river
- Islands: island_tropical, island_forest, island_arctic
list_map_presets returns the authoritative set at runtime — call it if unsure.
If they provided a description or no arguments, help them choose:
- Call
list_map_presetsto show available presets - Ask if a preset fits or if they want a custom config
- For custom configs, discuss: size, terrain types, vegetation density, roads/rivers, water, lighting, rooms/corridors/polygons
Step 2: Choose Output Location
Ask the user where to save the .dungeondraft_map file. Suggest a reasonable default like their Desktop or current directory. The tool returns a download link; you download the file to this location in step 4.
Step 3: Generate
From preset:
generate_map(preset: "<name>", seed: <random or user-specified>)
From custom config:
- Build the YAML config based on the discussion
- Validate first:
validate_map_config(config_yaml: "...") - If valid, generate:
generate_map(config_yaml: "...") - If errors, fix and re-validate
Step 4: Download the File
The result has download.download_url and download.filename. Download the file to the location from step 2:
curl -sS -f -H "Authorization: Bearer $MIMIR_API_TOKEN" \
-o "<path>" "$MIMIR_URL<download_url>"
The link works one time, for one hour.
Step 5: Report Results
Show the generation stats:
- Walls generated (room boundaries, corridors)
- Portals generated (doors, windows)
- Objects placed (trees, clutter, clumps)
- Paths generated (roads, rivers)
- Water polygons
- Contour paths
- Output file location
Remind the user they can open the file in Dungeondraft to view and edit the map.
Offer to regenerate with a different seed or adjusted config if they want variations.
List Mimir Campaigns
Use the list_campaigns MCP tool to show all available D&D campaigns, and get_active_campaign to learn which one is currently active (list_campaigns does not include active status, so compare its id against the id returned by get_active_campaign).
For each campaign, display:
- Campaign name
- Campaign ID
- Creation date
- Whether it's the active campaign (matches
get_active_campaign)
If no campaigns exist, offer to create one using create_campaign.
After listing, ask the user if they want to set one as active using set_active_campaign.
Search Monster Catalog
Use search_catalog with category: "monster" to find monsters matching the criteria.
Parse the arguments:
- If
querylooks like a creature type (undead, dragon, fiend, etc.), usemonster_type - Otherwise use
namefor partial matching - If
crcontains a dash, parse as cr_min and cr_max - If
cris a single value, use it for both min and max
Display results in a table format: | Name | CR | Type | Size | Source |
If searching within an active campaign, note that results are filtered to the campaign's enabled source books.
After showing results, offer to:
- Add a monster to a module
- Search with different criteria
- Get detailed stats for a specific monster
- Clone a monster as homebrew for customization
Search Spell Catalog
Use search_catalog with category: "spell" to find spells matching the criteria.
Parse the arguments:
- If
queryis provided, usenamefor partial matching - If
levelis provided, use as integer filter (0 = cantrips) - If
schoolis provided, useschoolfilter - If
classis provided, useclass_namefilter
Display results in a table format: | Name | Level | School | Source |
If searching within an active campaign, note that results are filtered to the campaign's enabled source books.
After showing results, offer to:
- Get more details about a specific spell
- Search with different criteria
- Clone a spell as homebrew for customization
MCP servers 1
Sponsors
Details
- Marketplace
- mimir-dm/mimir
- Source
- crates/mimir-mcp/plugin
- Author
- Colliery
- Category
- Productivity
- License
- MIT
- Keywords
- dnd, 5e, campaign, ttrpg, dungeon-master, mimir