darkest-dungeon-mcp
v1.0.0-beta.1
Published
Read-only MCP server for Darkest Dungeon 1 save data and gameplay knowledge
Maintainers
Readme
Darkest Dungeon MCP
A read-only Model Context Protocol (MCP) server for inspecting Darkest Dungeon 1 save data and retrieving verified gameplay knowledge.
The server decodes copied save files into a temporary directory, validates the decoded JSON, and exposes normalized campaign data without modifying the original saves. It also includes curated knowledge for curios, classes, combat, trinkets, camping skills, quirk treatment, and building-upgrade priorities.
This is an unofficial fan project. It is not affiliated with, endorsed by, or sponsored by Red Hook Studios or the Official Darkest Dungeon Wiki.
Requirements
- Node.js 20.12 or later
- For live saves: Java through
PATH,JAVA_HOME, or--java, plusDDSaveEditor.jar - A PC installation of Darkest Dungeon 1 for official localization, building and trinket definitions, combat skill details, hero progression and quest restrictions, and quirk definitions
Installation
Use the pinned beta package [email protected] with npx.
You do not need to clone this repository or build TypeScript.
The first launch downloads the package and its dependencies from npm.
Install Node.js and Java, download DDSaveEditor.jar from its
release page,
then configure a client that supports local stdio MCP servers.
Replace the profile, game, and JAR paths below with your own absolute paths.
The following is a Windows example using the common mcpServers format:
{
"mcpServers": {
"darkest-dungeon": {
"command": "cmd",
"args": [
"/c", "npx", "-y", "[email protected]",
"--save-dir",
"C:/path/to/Steam/userdata/STEAM_USER_ID/262060/remote/profile_0",
"--game-dir",
"C:/path/to/Steam/steamapps/common/DarkestDungeon",
"--decoder-jar",
"C:/absolute/path/to/DDSaveEditor.jar"
]
}
}
}Codex uses TOML instead of the JSON wrapper. Add this to
~/.codex/config.toml for a user-level installation:
[mcp_servers.darkest_dungeon]
command = "cmd"
args = [
"/c", "npx", "-y", "[email protected]",
"--save-dir", "C:/path/to/profile_0",
"--game-dir", "C:/path/to/DarkestDungeon",
"--decoder-jar", "C:/absolute/path/to/DDSaveEditor.jar",
]
startup_timeout_sec = 120
tool_timeout_sec = 120On macOS/Linux, use command = "npx" (or JSON "command": "npx")
and remove the initial "/c", "npx" arguments. Replace Windows paths with
paths accessible to the client process. The beta's clean-install test has
been verified on Windows with Node.js 22; other platforms are not yet verified.
Restart the client after saving its configuration, then inspect its MCP server
list or ask it to call get_game_state. See
MCP client configuration for exact locations,
commands, and troubleshooting instructions for Codex, Claude Code, Claude
Desktop, Google Antigravity, OpenClaw, and generic stdio clients.
--save-dir selects the live profile. Without it, the server uses the
checked-in decoded samples. --game-dir enables official localized names plus
verified building upgrades, trinket metadata and filters, combat skill details,
hero resolve levels, quest eligibility, and quirk analysis. The original profile
remains untouched: supported save files are copied to a temporary directory
before decoding.
For a demo without Java or a game installation, omit the three path options.
Ask the client to call refresh_game_state and check that snapshot.source
is sample. For your own campaign, supply --save-dir and confirm it is live.
The server runs locally, but tool results are passed to your MCP client and may
be sent to its AI provider. npm installation does not provide an AI subscription.
To update, replace the pinned version in the client configuration and restart the server. Keep the previous version string if you need to revert.
Server options
The stdio entrypoint accepts configuration directly and does not require a particular working directory:
npx -y [email protected] --save-dir "C:\path\to\profile_0" --game-dir "C:\path\to\DarkestDungeon" --decoder-jar "C:\path\to\DDSaveEditor.jar"Available options are --env-file, --save-dir, --game-dir,
--decoder-jar, and --java. Command-line options take precedence over
process environment variables, which take precedence over an optional .env
next to the installed package. Java is discovered through PATH or
JAVA_HOME when --java is omitted.
MCP tools
| Tool | Purpose |
| --- | --- |
| refresh_game_state | Reload the shared read-only save snapshot before a new analysis when the campaign has changed. |
| get_game_state | Return a combined campaign summary with localized estate resources, class counts, dungeon quest counts, and built-district names. |
| list_building_upgrades | List building upgrades and costs with localized building, tree, and heirloom names. |
| recommend_quirk_management | Separate negative-quirk removals from positive-quirk lock guidance with priorities, lock capacity, evidence, and localized quirk text. |
| list_heroes | Filter heroes by class, roster status, stress, party availability, and optional quest eligibility; localize class names with language. |
| get_hero | Return one hero with localized class, combat-skill, equipped-trinket, quirk, disease, affliction, and virtue names, resolve level, availability, optional quest eligibility, and town activity. |
| compare_heroes | Compare 2–8 heroes using localized class, skill, and risky-quirk names plus objective readiness, equipment, skill-position, and curated quirk-risk evidence. |
| list_quests | Filter available quests with localized titles, objectives, regions, lengths, and reward names. |
| get_quest | Return one quest by ID with localized official quest and reward text. |
| list_trinkets | Query up to limit trinkets across storage, heroes, and stores by ID, localized name, hero class eligibility, or rarity; class and rarity filters require DD_GAME_DIR. |
| recommend_trinkets | Recommend optimal trinkets for a hero or class, or match candidate heroes for a specific trinket based on estate ownership, tier rankings, and synergies. |
| plan_expedition | Build a quest briefing with verified eligibility, role pools, provisions, camping, and tactical guidance. |
| recommend_building_upgrades | Rank estate upgrades using current heirlooms, verified costs, exchange feasibility, and curated priorities. |
| query_classes | Query verified class guidance with official class, skill, and synergy names localized from the installed game. |
| query_combat | Query verified region and enemy guidance by name, region, threat type, or priority. |
| search_curios | Search verified curios by ID, localized name, alias, or region. |
| get_curio_advice | Return item-aware interaction advice and warnings with localized curio names. |
Live save tools reuse one read-only snapshot for up to two minutes so that a
multi-tool analysis observes a consistent campaign state and does not repeatedly
decode the profile. Call refresh_game_state when the user reports an in-game
change and a fresh snapshot is needed. Refreshing only replaces the server's
in-memory snapshot; it never writes to the game profile. Sample mode uses a
stable snapshot until explicitly refreshed.
Localization
Tools with a language input accept en, fr, de, es, pt-BR, ru,
pl, cs, it, zh-CN, ja, and ko; the default is en. These codes
map to the language IDs verified in the installed Darkest Dungeon 1 string
tables. Official display names are returned only when the corresponding game
string exists; otherwise the localized field is null or the documented
stable-ID fallback is used. Stable internal IDs remain available in either
case. Curated strategy, priority, and policy prose remains English source
material for the MCP client to summarize in the user's language.
Curio coverage includes shared curios, Ruins, Warrens, Weald, Cove, Courtyard, Farmstead, Darkest Dungeon, Old Road, and relevant Hamlet quests. Retired curios that are no longer used by the game are intentionally excluded. search_curios and get_curio_advice resolve official curio names from DD_GAME_DIR; availableItems accepts internal IDs or official display names in any supported language. The curated knowledge set retains search aliases and language-neutral interaction outcomes and advice.
Class knowledge covers all 18 playable Darkest Dungeon 1 classes and all 126 combat skills. query_classes resolves official class and skill names from DD_GAME_DIR; the knowledge set retains only search aliases and language-neutral strategy guidance. Skill guidance uses internal IDs verified against the installed game definitions and describes use cases, synergies, and cautions without duplicating exact position or target data.
list_heroes, get_hero, and compare_heroes accept language. When
DD_GAME_DIR is configured, heroClassName, combat skill name,
camping skill name, equipped trinket name, quirks[].name, afflictionName, and
virtueName values come directly from the installed game's localization files; stable
internal IDs remain available alongside them. In get_hero, equippedTrinkets
also includes official rarity, heroClassRequirements, class compatibility
isUsableByHeroClass, and stat effects. campingSkillDetails provides official
skill names, respite point costs, nighttime ambush prevention flags, disease cure flags,
and categorized utility. In compare_heroes, quirkTreatmentAnalysis.risk.riskyQuirks
entries also include localized names.
list_trinkets accepts id, query, location, heroClass, rarity,
limit (default 50, maximum 100), and language. It resolves official trinket
names, rarities, hero class requirements (with localized class names), and stat
buff/debuff effects from
DD_GAME_DIR, including base-game, official DLC, and backer trinkets. Filtering
by heroClass or rarity returns an explicit configuration error when installed
game definitions are unavailable instead of returning an unverifiable result.
Gold-priced trinkets use price with shardPrice: null; Color of Madness
trinkets use shardPrice with price: null, preserving the game's actual
purchase currency instead of treating shards as gold.
recommend_trinkets evaluates equipment options for a hero (heroId), a class
(heroClass), or a specific item (trinketId). It matches curated S/A/B/situational
tier ratings, class-specific synergies, and usage cautions against current estate
ownership (in_storage, equipped_by_self, equipped_by_other, in_store, or not_owned).
Pass exactly one of heroId, heroClass, or trinketId. By default, store-only
items are not treated as owned; they are exposed with isAvailableForPurchase
when onlyOwned is false.
When given trinketId, it returns candidate roster heroes ranked by suitability.
Each candidate includes current stress and party-selection availability, and
available candidates are ranked ahead of heroes blocked by a raid or town activity.
plan_expedition prepares a comprehensive expedition briefing (dossier) for a
target quest or dungeon region (questId, dungeon, difficulty, preferredHeroIds,
and language). It integrates strict eligibility pruning (resolve-level restrictions
and party-selection availability), explicit separation of unverifiable eligibility,
stress cautions, and class-knowledge-backed candidate pools across 4
functional roles (Frontline DPS, Control/Disruptor, Support/Stress Healer, and Primary
Healer), curated class-compatible trinket matches,
automated supply provision calculations with itemized gold costs based on dungeon
length and regional curio cleansing needs, nighttime ambush prevention and camping strategy
analysis (campingStrategy with 12-point respite plan and ambush prevention providers),
and target boss / regional combat tactics.
Heroes whose quest eligibility cannot be verified are returned separately under
unverifiedHeroes and are not included in the role pools.
recommend_building_upgrades accepts language and analyzes the estate's building
upgrades and current heirloom resources (Busts, Portraits, Deeds, Crests). It evaluates
strategic priority tiers (S, A, B, C), separates high-priority core targets
(Blacksmith, Guild, Stage Coach) from immediately affordable alternatives, calculates
heirloom shortages, simulates Heirloom Exchange feasibility with surplus currencies,
and recommends targeted farming dungeons (e.g. Weald for Deeds, Warrens for Portraits).
recommend_quirk_management accepts independent minimumNegativePriority and
minimumPositivePriority filters plus includeUnrated, heroId, language, and
limit. It separates negativeRemovals from positiveQuirks and reports each
positive quirk as lock_positive, keep_locked, do_not_prioritize, or unrated.
The result also reports the verified three-slot positive-lock capacity, current
usage, remaining slots, definition coverage, game effects, cautions, and evidence
sources. The checked-in policy currently contains 40 negative-removal rules and
16 general or conditional positive-lock rules. Official names and descriptions
are localized; priorities, reasons, cautions, and policy text remain English
editorial source material for the client to summarize in the user's language.
Town-facing and campaign tools accept language and resolve official building,
activity, district, upgrade-tree, heirloom, estate resource, class count, and
dungeon quest count names from DD_GAME_DIR. Stable IDs are retained alongside
localized display names.
Combat knowledge covers Ruins, Warrens, Weald, Cove, Courtyard (Crimson Court),
Farmstead (Color of Madness), their region-specific enemies, shared roaming enemies,
and key bosses / minibosses (Necromancer, Prophet, Swine Prince, Hag, Siren,
Drowned Crew, Collector, Shambler, Crocodilian, and The Miller).
query_combat accepts query, region, threat, priority, scope, and
language filters. Region display names and localized-name search come from
the installed game's localization files when DD_GAME_DIR is configured.
Enemy and dangerous-action names use the same localization source; English
strategy guidance remains language-neutral source material for the client to
summarize in the user's language.
The guidance describes qualitative priorities, dangerous actions, and counters.
It covers the listed base and DLC regions and curated bosses, but does not provide
live turn state or exact enemy stats.
Quirk management combines the current roster, installed game definitions, and a
conservative editorial policy. Negative rules focus on verified high-impact
penalties and forced interactions. Positive rules prioritize broadly applicable
speed, accuracy, defense, and opening-round effects while explicitly identifying
lower-value town or camping effects. Uncurated positive quirks can be returned as
unrated; special non-replaceable quirks are never curated as Sanitarium lock
targets. Results are guidance, not an absolute or exhaustive treatment order.
The evidence and priority policy is documented in
docs/QUIRK_MANAGEMENT_POLICY.md.
Combat skill levels combine per-hero purchases from persist.upgrades.json
with installed hero upgrade definitions. The raw values under
selected_combat_skills only identify selection data and are never reported as
levels. Without --game-dir, get_hero returns selected skills with
level: null rather than guessing.
With a configured game installation, combat skill details also include the
party positions where each skill can be used, its target side and positions,
whether it targets one, a group, or a random unit, and any forward or backward
movement. Position 1 is the frontmost position and position 4 is the rearmost
position for both sides. get_hero also summarizes the selected loadout as
objective per-position coverage, including positions where every selected
skill works and positions with the highest skill count. These fields do not
apply an editorial viability threshold.
Hero resolve levels are derived from the thresholds in the configured game
installation. Hero results also report whether each hero can be newly selected
for a party and list concrete blockers such as an existing raid or town
assignment. Pass a questId to list_heroes or get_hero to apply the
installed game's resolve-level restriction for that quest; eligibleOnly can
then restrict list_heroes to eligible heroes.
Knowledge data and attribution
Curios, classes, combat, trinkets, camping skills, quirk treatment, and
building-upgrade priorities live under data/knowledge.
The curio, class, and combat guidance is adapted from the
Official Darkest Dungeon Wiki,
and its records retain source URLs and verification dates. Other knowledge files
contain verified game identifiers and explicitly editorial recommendation data.
The wiki material was summarized, normalized into a machine-readable schema, reorganized by interaction, and supplemented with clearly marked recommendation metadata. No wiki images are included. The adapted knowledge data is distributed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International, matching the source license. Reuse of that data must preserve attribution, remain noncommercial, indicate changes, and use the same license for adaptations.
See LICENSE.md for the exact licensing scope. Source code and wiki-derived knowledge data are licensed separately.
Disclaimer
Darkest Dungeon and related names and trademarks belong to their respective owners. This software is provided without warranty. Back up save data before using third-party tools, even though this server is designed to be read-only.
For source development and testing, see the contributor guide.
