Dwarf Fortress (DFHack) MCP server

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:

threats, stocks, jobsandlabor, military, injuriesandhealth, defenses, and more.

• Sensors answer what is my fort doing right now? — fort_status,

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

• Reference answers how does Dwarf Fortress work? — gamedata is your

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

live game; if no fort is loaded they say so.

• Dwarf Fortress running with DFHack, with a fort loaded. The tools read the

runs with DFHack — no config file to edit. (The allowremote setting only governs connections from other machines and can stay false; a local MCP server reaches it either way.) Point elsewhere with DFHACKHOST / DFHACK_PORT.

• DFHack Remote RPC on localhost:5000. This is on by default whenever DF

source — see Development.)

• Node 20+ to run the published package. (Node 24+ only if you develop from

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.

Shortened. The full README is on GitHub.