MCP

dwarf_fortress_mcp: Let AI Agents Operate Dwarf Fortress Transactionally — Verify Lab Adapter and Platform Prerequisites Before Use

Best suited for users who want AI agents to operate a Dwarf Fortress civilization transactionally; note that it currently only has a deterministic lab adapter with no live DFHack adapter, and the preferred platform is Linux + Classic + DFHack.

Official source · dwarf_fortress_mcp

Install

cargo run --locked -p dwarf-fortress-mcp -- serve

dwarf_fortress_mcp is a semantic, transactional, replayable MCP control plane (Phase 0C scaffold, MIT licensed, implemented in Rust) that lets autonomous AI agents operate Dwarf Fortress as a long-lived civilization. It exposes a fixed set of 11 fortress.* tools over stdio (MCP 2026-07-28 modern-only), currently backed by a deterministic lab adapter.

Who It's For

  • Users who want AI agents to observe and operate Dwarf Fortress in a semantic, transactional way within a controlled lab environment: query world state, formulate plans, submit changes, take checkpoints, and replay.
  • Researchers and developers interested in a deterministic, replayable agent-game control plane.
  • Not for those who want to directly control a running Dwarf Fortress game: there is currently no live DFHack adapter, only a deterministic lab adapter.
  • Platform prerequisites: the Tier 1 reference target is Linux + Dwarf Fortress Classic (free) + DFHack; Linux + Premium and Windows are supported tiers; macOS (via Wine/Whisky/CrossOver) is explicitly best-effort, not a supported target. The control plane itself is version-agnostic and does not depend on the paid edition.
  • Toolchain requirements: safe Rust 2024, the latest nightly toolchain, and a closed dependency universe; the local qualification test scripts require nightly and locked/offline resolution.

First Attempt in 3 Minutes

Prerequisites: Rust installed (latest nightly toolchain) and the repository cloned. The default service form is a local stdio server, bound to localhost, single fortress, read-only capabilities, with no environmental filesystem or network access and no arbitrary command escape hatch — these are the officially stated safe defaults.

Recommended primary path (official run command):

cargo run --locked -p dwarf-fortress-mcp -- serve

serve starts the MCP 2026-07-28 modern-only stdio server (backed by the lab adapter). The binary also offers contract, doctor, demo, and other subcommands as secondary options.

For a first attempt, it is recommended to invoke low-risk read-only capabilities:

  • fortress.doctor: check the service's own status and verify that the server started and responds correctly.
  • fortress.observe / fortress.query: observe and query the fortress's current state without producing changes.

Success signals: the server responds to tool calls over stdio per the MCP protocol, fortress.doctor returns a healthy result, and fortress.observe returns a snapshot of the fortress state under the lab adapter.

Note: readOnlyHint or read-only tools only indicate that no write operations are performed; they do not mean zero risk, and you should not infer the absence of privacy boundaries from them. Actual change submission (fortress.commit) is a write operation that requires a plan ID, plan summary, prepare receipt, and expected anchors; changes are only permitted within officially authorized, short-lived capability scopes.

Use Cases

Case 1: Check service health and observe the world. After starting serve, call fortress.doctor to confirm the MCP server is ready, then call fortress.observe to get the fortress state under the lab adapter. Expected result: a semantic observation snapshot of the current world/fortress state with no write side effects.

Case 2: Transactional plan and commit. First use fortress.query to query a specific goal, then call fortress.plan to generate a plan, and finally — provided the appropriate capability scope is in place — submit with fortress.commit (requires plan ID, plan summary, prepare receipt, and expected anchors). Expected result: after submission, a receipt is returned; submitting the same plan again does not re-execute its effects but returns the previous receipt. If you need to interrupt mid-operation, use fortress.cancel or fortress.wait accordingly. This is a write operation; confirm side effects and scope before executing.

Usage Boundaries

  • Read/write nature: observe, query, explain, doctor, and similar tools are read-only; plan/commit/checkpoint/restore involve state writes or replay, with commit being an explicit write operation requiring the transactional elements mentioned above.
  • Safe defaults (officially stated): localhost, single fortress, read-only capabilities, no environmental filesystem/network access, no arbitrary command escape hatch; the default server does not expose arbitrary shell execution, Lua evaluation, DFHack command strings, memory writes, or file paths.
  • Key limitation: there is currently no live DFHack adapter, only a deterministic lab adapter; this means it cannot yet directly control a real, running game process.
  • Unconfirmed information: specific client integration configuration examples, full parameter details for checkpoint/restore, and similar items are not covered in the collected evidence; consult the repository README and documentation before use.