Skip to main content
Glama
README.md
# dfhack-mcp

An [MCP](https://modelcontextprotocol.io) server that gives an AI client live
access to **Dwarf Fortress** through [DFHack](https://dfhack.org). 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](#taking-action-actuators)).

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](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](docs/tools/README.md).

## 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`:

```json
{
  "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`](https://www.npmjs.com/package/dfhack-remote-node) RPC
transport — are pulled from npm automatically.

Clients that browse the [official MCP Registry](https://registry.modelcontextprotocol.io)
can find this server there as **`io.github.alexanderolvera/dfhack-mcp`**; the
listing is generated from [`server.json`](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?

```sh
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](#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](CONTRIBUTING.md#fog-of-war-the-reveal_hidden-opt-in).

- **`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.

```json
{
  "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](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:

```json
{ "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](#taking-action-actuators)).
- **`dfhack_command_run` is missing** — it has its own gate. Set
  `DFHACK_MCP_COMMANDS=1` (see [Running DFHack's own commands](#running-dfhacks-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.

## Development

To hack on the server itself, clone and run the TypeScript entry directly (Node
24+ — it runs the sources via type-stripping, no build step):

```sh
git clone https://github.com/alexanderolvera/dfhack-mcp.git
cd dfhack-mcp
npm install        # or: npm run bootstrap  (installs + runs the T0 contract check)
node src/index.ts
```

Point an MCP client at the checkout with `"command": "node", "args":
["/absolute/path/to/dfhack-mcp/src/index.ts"]`.

All version-fragile DFHack field access lives in **real `.lua` scripts** under
`src/dfhack-queries/` (one per tool), invoked by name with native argv — so a
DF/DFHack version bump is a localized fix and query parameters are injection-safe
by construction. Each tool is a thin TypeScript wrapper in `src/tools/`.

**Facts, not advice.** Tools _sense_ — they return what is true about the fort and
the world, the way a player reads a screen. They do not say what to build or how
to fight; that judgment is the agent's. A field that says _what to do_ is advice —
leave it out.

Every tool is verified against a **live fort** with the tiered harness (`npm run
verify:t0` … `t2`) — never mocks. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the
tool-authoring split and the verification workflow, and
[`docs/VERIFY.md`](docs/VERIFY.md) for the harness tiers.

## License

ISC — see [LICENSE.md](./LICENSE.md).

TDQS

A4.2/5.0

Scored across 37 tools

Disambiguation4/5

Each tool targets a distinct subsystem (wiki, artifacts, burrows, etc.), and the extremely detailed descriptions make them individually clear. However, several tools overlap in reporting hostiles (threats, defenses, military) and terrain/water facts (environment, geology, fluids), so an agent could initially hesitate before picking the right one. The primary purposes differ enough that only minor confusion exists.

Naming Consistency4/5

All names use consistent lowercase snake_case and are mostly plural nouns or noun phrases (e.g., stockpiles, rooms_and_zones). A few are verb+noun (find_unit, wiki_lookup) or a bare verb (identify), which is a minor deviation but still follows the same casing style and remains readable. The pattern is predictable overall.

Tool Count2/5

At 37 tools, this server sits well above the 25-tool threshold the rubric marks as too many. While Dwarf Fortress is complex, several tools could be consolidated (e.g., threats/defenses/military, environment/geology/fluids), inflating the surface without a proportional increase in distinct capabilities. The count feels heavy rather than lean.

Completeness5/5

The tool surface offers comprehensive read-only coverage of the loaded fort: units, labor, military, health, supplies, structures, trade, and world data. Chaining is well-designed (find_unit -> citizen, wiki_search -> wiki_lookup) and there are no obvious dead ends. The only missing features are actuator tools, which are outside this server's stated read-only scope.

Maintenance

ActivityNo data
ResponsivenessOutdated data