dfhack-mcp

# dfhack-mcp

An [MCP](https://modelcontextprotocol.io) 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](#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), 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](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

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, 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.

  | 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 (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