elden-ring-mcp

MCP server exposing Elden Ring (base game + Shadow of the Erdtree) weapon, spell, talisman, and armour data — with an optional bring-your-own-corpus ingestion pipeline for lore, tier-takes, and community notes.

Built by someone who has never played Elden Ring, for a friend who does — the game arrived purely as sets of abstract data (entities, scalings, annotations with provenance), taken on for the intellectual excitement of mapping a territory from the outside.

SQLite-backed. Game data bootstrapped from eldenring.fanapis.com plus a curated SotE delta. The lore/tier/community tools are inert until you supply your own transcript corpus.

---

Install

npm install

---

Bootstrap game data

npm run bootstrap    # pulls base-game data from eldenring.fanapis.com → data/elden-ring.db
npm run load-sote    # loads the curated Shadow of the Erdtree delta

Both commands are idempotent. Run them once before starting the server.

---

Register with Claude Code or Claude Desktop

Create or edit .mcp.json in your project root (Claude Code) or add to claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "elden-ring": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/absolute/path/to/elden-ring-mcp"
    }
  }
}

Replace /absolute/path/to/elden-ring-mcp with the actual path to this repo on your machine (e.g. C:/Users/you/Projects/elden-ring-mcp on Windows).

---

What works out of the box

Tool	No corpus	With corpus
lookup_item	Full (fanapis + SotE delta)	same
search_weapons	Full (fanapis + SotE delta)	same
get_item_details	Full (fanapis + SotE delta)	same
compare_items	Full (fanapis + SotE delta)	same
list_categories	Full (fanapis + SotE delta)	same
get_catalyst_scaling	Full (fanapis + SotE delta)	same
get_location	Partial (fanapis location prose only)	+ corpus location guides
get_lore	Inert — graceful empty state	Full
get_tier_take	Inert — graceful empty state	Full
get_community_vibe	Inert — graceful empty state	Full

The three corpus-dependent tools return a helpful "no X is on file" message rather than an error when no corpus has been ingested — they will never crash a session.

---

Bring your own corpus

The lore, tier-take, and community-vibe tools come alive when you supply your own transcript .txt files and a routing config that tells the pipeline how to parse them.

Step 1 — Drop transcripts

Place your .txt transcript files in the corpus/ directory. The directory is gitignored; nothing you put there will be committed.

Step 2 — Configure routing

cp corpus.config.example.json corpus.config.json

Edit corpus.config.json. Each entry in routes maps a filename pattern (case-insensitive regex) to a parse mode and annotation kind:

{
  "routes": [
    {
      "pattern": "location|where to find",
      "parse_mode": "chapter",
      "annotation_kind": "location",
      "entity": "weapon",
      "source_kind": "location_guide"
    },
    {
      "pattern": "ranking|tier list|worst to best",
      "parse_mode": "number_inline",
      "annotation_kind": "tier_commentary",
      "entity": "weapon",
      "source_kind": "ranking"
    }
  ]
}

See corpus.config.example.json for the full set of patterns and parse modes (chapter, number_inline, llm_lore, skip).

Step 3 — Run ingestion

npm run ingest

Phase 1 (no API key required)

Phase 1 is deterministic: it parses structured transcripts (chapter-format location guides, numbered ranking lists) and writes attribution rows to the database. No API key needed. If LLM_API_KEY is unset, the pipeline stops after phase 1 and tells you what was skipped — you still get location and tier annotations.

Phases 2 and 3 (LLM, optional)

Phases 2 and 3 use an LLM to extract lore notes and community opinions from unstructured prose. To enable them, set LLM_API_KEY:

LLM_API_KEY=your_key npm run ingest

The default endpoint is Groq's free tier (https://api.groq.com/openai/v1). You can override any of these env vars:

Variable	Default	Purpose
LLM_API_KEY	(unset)	API key for phases 2/3
LLM_BASE_URL	https://api.groq.com/openai/v1	Any OpenAI-compatible endpoint
LLM_MODEL	openai/gpt-oss-120b	Model to use for extraction
LLM_DELAY_MS	1500	Minimum ms between calls (free-tier RPM compliance)

You can also override the database path and corpus directory:

Variable	Default	Purpose
ELDEN_RING_DB	data/elden-ring.db	SQLite database path
CORPUS_DIR	corpus	Directory containing transcript .txt files

---

Attribution

Every annotation row in the database carries a source field identifying the transcript it came from. Ranking annotations also carry rank_in_source (the reviewer's original ordinal position). All tools that return corpus-derived content surface this attribution in their output, so you can always see where a claim came from.

---

NOTICE

This is an unaffiliated fan project. "Elden Ring" and all game content, names, and assets are the property of FromSoftware, Inc. and Bandai Namco Entertainment. This project is not endorsed by or associated with the rights holders.

The MIT licence covers only the code in this repository. It does not grant any right to game assets or to any third-party content a user may ingest.

This repository ships no transcript-derived content. The lore, tier-take, and community-vibe tools are inert until you supply your own corpus. Every annotation carries a source field so that any derived commentary is attributed to its origin; users who ingest third parties' transcripts are responsible for that use.

See NOTICE for the full statement.