# Dwarf Fortress (DFHack) MCP server

> Provides an AI client with live access to a running Dwarf Fortress game through DFHack to observe fort status, stocks, threats, and unit details.

- Repository: https://github.com/alexanderolvera/dfhack-mcp
- Page: https://hostedmcp.org/servers/alexanderolvera/dfhack-mcp
- Transport: stdio
- Stars: 2
- License: ISC
- Latest version: 1.4.1

## Install

### Claude Code

```sh
claude mcp add dfhack-mcp -- npx -y dfhack-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "dfhack-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dfhack-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "dfhack-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "dfhack-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"dfhack-mcp","type":"stdio","command":"npx","args":["-y","dfhack-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "dfhack-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dfhack-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add dfhack-mcp -- npx -y dfhack-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.dfhack-mcp]
command = "npx"
args = ["-y", "dfhack-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user dfhack-mcp npx -- -y dfhack-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "dfhack-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dfhack-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `DFHACK_HOST` | no | no | Host running DFHack's remote RPC server. Defaults to 127.0.0.1. |
| `DFHACK_MCP_ACTUATORS` | no | no | Set to any value to expose the write tools. Unset, the server is read-only. |
| `DFHACK_PORT` | no | no | Port for DFHack's remote RPC server. Defaults to 5000. |

## FAQ

### Does this server allow the AI to change things in my game?

By default, the server is read-only. Actuators that can change the fort, such as assigning labor or pulling levers, are hidden and require explicit opt-in to enable.

### Can the AI see parts of the map that are currently under fog of war?

Undiscovered tiles and units are hidden by default, but most tools include an optional parameter to bypass fog of war and reveal hidden information.