Dwarf Fortress (DFHack)

dfhack-mcp

An MCP server that gives an AI agent a live window into your Dwarf Fortress fort — a co-pilot and early-warning advisor, not an autopilot. Point Claude (or any MCP client) at it and ask _"how's my fort doing?"_ — it reads happiness, threats, stocks, jobs, health, and defenses straight from the running game and answers in plain language.

Read-only by default. The 37 sensor and reference tools only observe the game. A handful of actuators that _change_ the fort — queue manager orders, apply quickfort blueprints, assign labor, sound the civilian alert, pull a lever — ship behind an explicit opt-in and stay hidden until you enable them (see Taking action).

Two kinds of tools:

• Sensors answer _what is my fort doing right now?_ — fort_status, threats, stocks, jobs_and_labor, military, injuries_and_health, defenses, and more.
• Reference answers _how does Dwarf Fortress work?_ — game_data is your world's ground truth (its loaded raws), the wiki_* tools are the general explanation, and identify fuses the two for _"what is this creature and how do I handle it."_

It returns facts, not advice — already-summarized JSON that reads like a glance at the screen, leaving the judgment to the agent.

Every tool has a reference page — parameters, return shape, real example output, caveats — in docs/tools.

Quick start

The package is published to npm and ships a prebuilt bundle — there is nothing to build. Point your MCP client at it with npx:

{

"mcpServers": { "dfhack": { "command": "npx", "args": ["-y", "dfhack-mcp"] } } }

That's it for Claude Desktop / Claude Code / any stdio MCP client. npx -y dfhack-mcp fetches and runs the latest release; its runtime dependencies — the MCP SDK, zod, and the dfhack-remote-node RPC transport — are pulled from npm automatically.

Clients that browse the official MCP Registry can find this server there as `io.github.alexanderolvera/dfhack-mcp`; the listing is generated from server.json and points at the same npm package, so either route installs the identical build.

Then just have your fort running (next section) and ask your agent something like _"check on my fort and flag anything urgent."_

Prefer a pinned global install?

npm install -g dfhack-mcp     # then set "command": "dfhack-mcp", "args": []

Requirements

• Dwarf Fortress running with DFHack, with a fort loaded. The tools read the live game; if no fort is loaded they say so.
• DFHack Remote RPC on localhost:5000. This is on by default whenever DF runs with DFHack — no config file to edit. (The allow_remote setting only governs connections from _other_ machines and can stay false; a local MCP server reaches it either way.) Point elsewhere with DFHACK_HOST / DFHACK_PORT.
• Node 20+ to run the published package. (Node 24+ only if you develop from source — see Development.)

What you can ask it

Your agent picks the tools; you just describe what you want. The tools below are what it has to work with.

Sensors — the state of your fort

No arguments; each reports on the loaded fort.

• `fort_status()` — name, date/season, population, wealth, happiness breakdown, pre-triaged alerts.
• `stocks()` — food/drink as days-of-supply, plus critical material counts and notable low/high lists.
• `threats()` — dangerous units grouped by type; active vs. contained, great-danger/invader/undead flags, plus each group's decisive traits (trapavoid, flier, fire, webber, building-destroyer, ranged).
• `unmet_needs()` — the needs system aggregated: the top unmet needs ranked by how many dwarves are distracted, and how starved each is.
• `jobs_and_labor()` — workforce utilization: busy vs. idle adults (children excluded), idle %, and a ranked breakdown of active jobs.
• `military()` — squads (each with its squad_id, the id squad_orders targets), enlisted soldiers, filled positions, readiness against hostiles on the map, and per-squad roster equipment gaps (missing uniform pieces), ammo, and active training order.
• `injuries_and_health()` — wounded / patients / bedridden / unconscious counts, plus the care needed (diagnosis, surgery, suture, …).
• `defenses()` — active hostiles with map positions and distance/direction/z-delta to the fort core and nearest drawbridge, plus a controllable-structure inventory (bridges, levers, floodgates, hatches, cage traps, doors).
• `burrows()` — every burrow's size and membership, plus the civilian-alert safety-burrow set (configured/active/linked burrows) — the read half of civilian_alert.
• `mechanisms()` — every lever's position, state, and linked target(s) (bridge/door/floodgate/hatch/support/weapon-trap); pressure-plate trigger conditions; unlinked levers and bridges.
• `moods()` — any active strange mood (fey/secretive/possessed/macabre/fell): the dwarf, driving skill, workshop state, and each demanded material cross-referenced against fort stock — the "demands bones, fort has zero" early warning.
• `mandates_and_justice()` — the nobility's overhead: active production mandates and export bans, unmet noble room demands, and justice state (open cases, convictions awaiting punishment, restraint capacity).
• `rooms_and_zones()` — the facility inventory, each count paired with its demand-side number: bedrooms, dining halls, the hospital, wells, temples, taverns, libraries, guildhalls, and coffins free vs. dead awaiting burial. The supply-side companion to unmet_needs().
• `trade()` — the caravan lifecycle and trade depot: depot existence/completeness and wagon-accessibility, caravans present and their state, broker assignment/presence, and the count and approximate value of goods staged in the depot.
• `environment()` — ambient conditions right now: season and weather, surface temperature and whether exposed water is frozen, the embark's biome alignment (evil/good/reanimating), and — for each cavern the fort has already breached — whether it is open or sealed. Fog-of-war honest.
• `find_unit(query)` — look up citizens by name fragment or profession; a compact dossier per match (profession, age, stress, job, squad, health flags). Chain into citizen for depth.
• `citizen(unit_id)` — the full character sheet for one dwarf: social graph (spouse/parents/children/friends/grudges, each with a unit_id you can walk), worshipped deities, notable personality extremes, skills of note, likes/detests, and recent thoughts tied to current stress.
• `site_history()` — the fort's entry in the world saga: founding, the fort name in Dwarven + English with etymology, prior sieges/battles at the site, and notable figures who died here.
• `artifacts_and_engravings()` — the fort's masterworks and notable engravings.
• `chronicle()` — a scannable recent-events feed for the fort.

Spatial (fog-of-war honest — undiscovered tiles never leak):

• `map_overview()` — cheap orientation to run _before_ any per-tile read: map extents, the fort-core coordinate, the surface z-level, the z-levels carrying player activity (digging/construction), and stairways as vertical columns. Fixed-size regardless of fort size.
• `tile_region(z?, x0?, y0?, x1?, y1?)` — a bounded window of one z-level as an ASCII grid plus a self-describing legend. Undiscovered tiles stay ?. All params optional: none → a 60×40 window on the fort core; z alone → that level's centroid; explicit corners otherwise. Hard-capped at 100×100 (oversized requests are clamped, never errored). Renders the map; never designs it.

• `geology(reveal_hidden?)` — a one-call geological survey (revealed-info only by default): surface z-level, the exposed layer stack with material names, the aquifer (light vs. heavy, z-range), discovered caverns, whether the magma sea is reached, and surface water. reveal_hidden: true bypasses fog of war (a debug/spoiler switch, default off).

Reference — how DF works

wiki_* are pure HTTP and work without the game; game_data / identify read a loaded world.

• `game_data(query, kind?)` — your world's raws across six kinds (creature, material, plant, reaction, item, building; default creature). Ground truth for procedural creatures (demons, forgotten beasts, titans) that never reach the wiki. query is a token (DEMON_4, INORGANIC:IRON), a name ("plump helmet"), or — for creatures — a live unit_id. One strong hit → a full dossier; several → a disambiguation list; none → {"match_count":0,"matches":[]}.
• `identify(query)` — _"what is this creature and how do I handle it"_ in one call: fuses game_data (your world's raws) with wiki_lookup (strategy). Returns the dossier (its flags[]/interactions[] carry facts like _TRAPAVOID → mechanical traps don't work_) plus 1–2 trimmed wiki excerpts. Reach for it when a threat appears.
• `wiki_search(query)` — search the DF wiki for candidate titles + cleaned snippets (biased to the DF2014 namespace).
• `wiki_lookup(title, section?, refresh?)` — fetch a wiki article as clean text, pinned to DF2014; follows redirects, honors section fragments, cached ~30 days.

Taking action (actuators)

By default every tool above only reads the game. The actuators _change_ the fort, so they ship behind an explicit switch — set DFHACK_MCP_ACTUATORS and they appear in the tool list; leave it unset and the server is strictly read-only.

{

"mcpServers": { "dfhack": { "command": "npx", "args": ["-y", "dfhack-mcp"], "env": { "DFHACK_MCP_ACTUATORS": "1" } } } }

Every actuator uses the same preview → confirm → apply → undo safety loop, so a change is never a surprise:

1. Preview (dry-run). The agent calls the tool with the operation fully specified but no confirmation token. It gets back a preview of exactly what would change — facts, never advice — plus a single-use confirm_token. Nothing is written. If the operation can't be applied as asked (e.g. a malformed blueprint), the preview reports why and no token is issued.
2. Apply. The agent calls again with the same arguments plus that token. The server re-checks that _the thing being acted on_ hasn't changed since the preview; if it has, the token is void and the agent re-previews. On success it gets an undo handle and a readback from the matching sensor confirming the change.

Tokens are single-use and target-scoped: an unrelated change elsewhere in the fort does not void them, but a change to the target does. Each