Dwarf Fortress (DFHack) MCP server

dfhack-mcp

An MCP server that gives an AI client live access to Dwarf Fortress through DFHack. It is an access layer: it reports what is true in the running game and executes exactly what it is asked, and it leaves deciding what matters, and what to do about it, to the client. Point Claude (or any MCP client) at it and ask "how's my fort doing?". The client reads happiness, threats, stocks, jobs, health and defenses straight from the game and does the reasoning itself.

Read-only by default. The 39 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), and dfhack_command_list lists what DFHack itself can do.

It returns facts, not advice: structured JSON in DF's own terms, with no thresholds, triage or strategy text layered on top. Rates, alerts and game knowledge belong to the client. docs/migrating-to-2.0.md lists what moved out of the server in 2.0.

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

Each reports on the loaded fort, except game_state(), which works at any screen.

Fog of war is on by default. Undiscovered tiles, the units standing on them and undiscovered caverns never appear. What a player may see past that is the client's call, so every fog-gated tool takes the same optional reveal_hidden: true to bypass it, and every response from one reports fog_of_war: "applied" | "bypassed". The fog-gated tools are defenses, environment, fluids, fort_health, fort_status, geology, historical_figure, livestock_and_pastures, map_overview, military, rooms_and_zones, threats, tile_region and unit_appearance. A bypassed full-map scan (fluids, geology) reads every tile, so it takes longer; raise DFHACK_MCP_TIMEOUT_MS on a large map. See CONTRIBUTING's fog-of-war section.

• game_state() — DFHack and DF versions, game mode (title/fortress/adventure/other), whether a world and map are loaded, paused, the raw clock (year, year_tick, formatted date), and the world/fort identity. The one tool that works with no fort loaded; cheap enough to poll.
• fort_status(reveal_hidden?) — name, date/season, identity (world, save folder, site, civ), population, wealth, happiness breakdown, recent deaths, hostiles on map.
• stocks(category?) — raw usable counts of food, drink and key materials, a usable count for every DF item type (optionally one category), and the population to normalize them by.
• threats(reveal_hidden?) — 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(reveal_hidden?) — 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(reveal_hidden?) — 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(reveal_hidden?) — 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(reveal_hidden?) — 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.
• 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.
• unit_appearance(unit_id, reveal_hidden?) — the portrait read for one unit: DF's appearance modifiers (eyes, nose, hair length, build, ...) as raw values with their description band, hair/beard styling, hair/skin/eye colors as DF names them (including age graying), missing parts and scars, and everything worn or wielded with material, quality, wear, dye, and decorations.
• 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.
• historical_figure(hf_id, reveal_hidden?) — one figure's legends entry, dead or alive, fort-dweller or not: name in its native language + English, race/caste, birth and death (cause, site, slayer with hf_id), entity affiliations and positions held, relationships and worshipped deities (each with an hf_id you can walk), site links, kills, and the saga events that involve them.
• artifacts_and_engravings() — the fort's masterworks and notable engravings.
• chronicle() — a scannable recent-events feed for the fort.

Spatial (with fog applied, undiscovered tiles never leak):

• map_overview(reveal_hidden?) — 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?, reveal_hidden?) — a bounded window of one z-level as an ASCII grid plus a self-describing legend. Undiscovered tiles stay ? unless reveal_hidden. 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.

  glyph	meaning	glyph	meaning
  ?	undiscovered (fog of war)	+	constructed floor
  #	undug stone / wall	~	water / brook
  ,	undug soil (sand/clay/loam)	%	magma
  .	dug floor / walkable ground	W	workshop / furnace
  F	fortification	S	stockpile
  r	ramp	M	machine (gear/axle/pump/wheel/windmill)
  v	ramp top	n	furniture (bed/chair/table/door/etc)
  < > x	up / down / up-down stair	(space)	open space
  T	tree

• geology(reveal_hidden?) — a one-call geological survey: 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.

Reference — how DF works

game_data reads a loaded world; dfhack_command_list works without one.

• 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":[]}.
• dfhack_command_list(filter?) — every command DFHack itself ships (built-ins, plugins, scripts) from DFHack's own ls: name, one-line help, and tags, plus the tag list from tags. filter is a tag or a name substring. Reports what exists, not what to run; works without a fort.

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 actuator names its own reversal path.

Manager work orders

• work_order_list(after_id?) — read-only, always available. The fort's manager orders as facts: id, job type, output item/material, amount total/left, repeat frequency, bound workshop, and per-order validation state. Paged (cap 256) with a cursor.
• work_order_create(job_type, amount, frequency?, material?, item_type?) — queue a new order; the preview flags would_duplicate and manager_present. Reversal: work_order_cancel.
• work_order_cancel(order_id) — remove one order by id; the undo handle is a recreate spec (with a faithful flag when a workshop binding or conditions can't be fully restored).

Quickfort blueprints — designate dig/zone from an agent-drafted quickfort CSV. There's no separate read sensor: blueprint_apply without a token is the preview.

• blueprint_apply(csv, anchor_x, anchor_y, anchor_z, mode) — designate from a #dig or #zone blueprint; the top-left cell maps to the anchor. The dry-run parses quickfort's own stats and previews tiles affected, footprint, and fog-of-war tiles under it (a fact, never blocked). A malformed blueprint blocks with no token (quickfort would partially apply). v1 scope: dig + zone only — build/place are rejected. Reversal: blueprint_undo.
• blueprint_undo(csv, anchor_x, anchor_y, anchor_z, mode) — revert a dig/zone designation via quickfort's native undo (same csv/anchor/mode). The token signs a per-cell digest, so any per-cell drift voids it.

Labor via work details

• work_details() — read-only, always available. Every work detail (the game's labor groups): name, mode, the labor tokens it enables, and its assigned citizens (id-sorted, capped at 200 with the full member_count).
• assign_work_detail(unit_id, detail, enabled) — add or remove one citizen to/from one detail. The preview reports currently_member, resulting_members_count, and only_member; an already-satisfied request previews as a no-op. Reversal: the same call with enabled inverted.

Emergency response

• burrows() — read-only, always available. Every burrow's size and membership, plus the civilian alert's own state: configured (has the fort ever set one up), active (is it sounding right now), and the linked burrow ids.
• civilian_alert(burrow, enabled) — add or remove one burrow from the civilian-alert safety set. enabled=true also sounds the alarm if it wasn't already; enabled=false only silences it once the set becomes fully empty. Reversal: the same call with enabled inverted.
• mechanisms() — read-only, always available. Every lever/pressure-plate's position and linked target(s) (bridge/door/floodgate/hatch/support/weapon-trap), plus unlinked levers and bridges.
• pull_lever(lever_id, urgent?) — queue a job for a dwarf to pull a named lever (urgent defaults to do-now priority). This queues the job; the physical toggle happens once a dwarf completes it, not on apply. Reversal: pull the same lever again.
• squad_orders(squad_id, order, ...) — order a squad to move to a tile, kill named units, or cancel its orders. The highest-stakes actuator here: it sends real dwarves into real combat, and the ones who die stay dead. Orders replace rather than stack (DF treats a squad's order list as its whole standing instruction set), so an apply first clears what the squad was already doing. A kill target on an undiscovered tile is refused — targeting it would act on knowledge the fort doesn't have. Reversal: order="cancel", which releases the squad; it does not walk anyone back or un-fight a fight.

Saving the game

• game_save() — checkpoint the fort with a quicksave before a large or risky change, so a bad batch can be rolled back by loading the save. Takes no arguments; the dry-run previews the fort and game date being frozen. Two facts to know: the write is asynchronous (DF commits it over the next few frames — the readback confirms the quicksave dispatched, not that the file landed) and it routes through DF's autosave, so it lands in a rotating "autosave" folder per your DF settings rather than overwriting the loaded save. Irreversible: to roll back, load the appropriate save/autosave in DF. Fortress mode only.

Running DFHack's own commands

dfhack_command_list shows everything DFHack can do. dfhack_command_run(command, args?, confirm_token?) runs a small, hand-reviewed allowlist of those commands, and only when DFHACK_MCP_COMMANDS=1 is set. That gate is separate from DFHACK_MCP_ACTUATORS, and neither one enables the other. Any other command line returns {"error":"not allowlisted"} and never reaches DFHack.

The allowlist is matched per subcommand:

• Read-only, run directly: seedwatch [status], instruments [list], prospect [-s <sections>] [-v] (revealed map only; all/hell are refused).
• Mutating, preview → confirm: enable seedwatch, disable seedwatch, seedwatch <PLANT_ID|all> <target>, seedwatch clear, instruments order <name> [qty]. DFHack has no dry-run for these, so the preview reports the state the command acts on. The apply result reports the undo: the prior seedwatch targets to restore, or the created manager order ids to cancel with work_order_cancel.

The full allowlist, with each entry's safety note, is in docs/tools/dfhack_command_run.md.

Configuration

All optional, set in your MCP client's env for the server:

Variable	Default	Effect
DFHACK_HOST	127.0.0.1	Host where DFHack's Remote RPC is listening.
DFHACK_PORT	5000	Port for DFHack's Remote RPC.
DFHACK_MCP_ACTUATORS	(unset)	Set to 1 to expose the write actuators (off = strictly read-only).
DFHACK_MCP_COMMANDS	(unset)	Set to 1 to expose dfhack_command_run, which runs an allowlist of DFHack's own commands (separate from the actuator gate).
DFHACK_MCP_DEV	(unset)	Set to 1 to expose run_lua, a raw DFHack Lua escape hatch (reads and writes game state; for tool authors only).
DFHACK_MCP_QUERY_DIR	src/dfhack-queries/ (dev) / dist/dfhack-queries/ (bundled)	Overrides the directory from which the MCP query scripts are loaded.
DFHACK_MCP_TIMEOUT_MS	30000	Per-call deadline, in milliseconds, for each DFHack RPC call. A call that misses it returns TIMEOUT, resets the connection, and is never retried.

Errors

Every error payload carries a stable, machine-readable code next to the human-readable error message, so a client can tell the states apart without matching message text:

{ "error": "no fort loaded", "code": "NO_FORT" }

code	Meaning
NOT_CONNECTED	DFHack could not be reached, even after one reconnect attempt.
NO_FORT	DFHack is reachable, but no fort is loaded.
NO_GAME	No world is loaded at all (game_data).
NOT_FOUND	The id you passed (a unit, a historical figure) does not exist.
INVALID_ARGUMENT	The call was well-formed, but the arguments or the game state reject it (for example, a stale confirm_token, or a command outside the allowlist).
TIMEOUT	DFHack accepted the call but did not answer within DFHACK_MCP_TIMEOUT_MS. The call is not retried, so it may have partly run.
SCRIPT_ERROR	The query script or DFHack command ran and failed.

NOT_CONNECTED, TIMEOUT, SCRIPT_ERROR and the actuators' INVALID_ARGUMENT come back as MCP tool errors (isError: true). The others (the no-fort guard, a missing id) are ordinary tool output. Arguments that fail a tool's input schema are rejected by the MCP SDK before the tool runs, as plain text with no code.

Troubleshooting

• {"error":"no fort loaded","code":"NO_FORT"} — DFHack is reachable but you're at the title screen or in the menus. Load a fort in Fortress mode.
• "code":"TIMEOUT" — DFHack is reachable but did not answer in time (the game is hung, a modal dialog is open, or a long save is running). The next call reconnects. Raise DFHACK_MCP_TIMEOUT_MS if your fort is large enough that a normal call takes longer than 30 seconds.
• An error about not reaching DFHack — Dwarf Fortress isn't running with DFHack, or the RPC port differs. Confirm DF is up with DFHack and that DFHACK_HOST / DFHACK_PORT match (defaults 127.0.0.1:5000).
• The tools don't show up in your client — restart the MCP client so it relaunches the server; a running server won't pick up a config change.
• The write tools are missing — that's the default. Set DFHACK_MCP_ACTUATORS=1 (see Taking action).
• dfhack_command_run is missing — it has its own gate. Set DFHACK_MCP_COMMANDS=1 (see Running DFHack's own commands).
• First call after loading a fort errors once, then works — a freshly-started DFHack can reject the very first tool call while it finishes registering the query scripts; retry once.