@tibia.sh/tibiawiki-mcp

tibiawiki-mcp

An offline MCP server for TibiaWiki. It answers the questions the wiki itself cannot:

• Which creatures are weak to fire and give over 500 experience?
• What drops a Dragon Shield, and how likely is it?
• Where do I buy a Steel Helmet, and for how much?

The server makes no network calls. Every answer comes from a local SQLite snapshot you build yourself, so queries return in milliseconds and work offline.

Why it exists

TibiaWiki runs on Fandom without Cargo, Semantic MediaWiki or CirrusSearch, so there is no way to query it by attribute — every structured value is trapped inside Infobox wikitext, and the built-in search returns Dragon Necklace for fire resistant dragon. The public REST API over the same wiki exposes exactly one query parameter. Building a local index is the only way to ask a real question, and it costs about three minutes.

Requirements

• Node ≥ 22.13 to run it (node:sqlite landed in 22.5 and is unflagged from 22.13).
• Node ≥ 22.18 to develop it — the test suite runs TypeScript directly, and type-stripping is only on by default from 22.18. Consumers are unaffected: the published package ships compiled JavaScript.
• uv to build the index.

Install

pnpm add -g @tibia.sh/tibiawiki-mcp
tibiawiki-mcp build-index      # ~3 minutes, ~14 MB

Use with Claude Code

Two ways, and they ship different things.

As an MCP server only — the npm package:

claude mcp add --transport stdio tibiawiki -- npx -y @tibia.sh/tibiawiki-mcp

As a plugin — the server plus a skill that teaches an agent how to query it (name resolution, the 100-is-neutral modifier convention, the data quirks that produce wrong answers). The plugin pieces never reach the npm tarball, because package.json has files: ["dist", "data/spell-areas.json"].

Marketplace install is not supported yet. .mcp.json points at ${CLAUDE_PLUGIN_ROOT}/dist/index.js, dist/ is deliberately not committed, and Claude Code does not run a build or a pnpm install for a plugin it fetches. A marketplace or bare git clone install therefore starts with no server. Use the local checkout below, which builds first. Shipping dist/ or publishing a prebuilt bundle would fix this and is not done here.

git clone https://github.com/tibia-sh/tibiawiki-mcp
cd tibiawiki-mcp && pnpm install && pnpm build   # dist/ is gitignored, so build once
claude --plugin-dir .

The build step is not optional: dist/ is deliberately not committed, and .mcp.json points at ${CLAUDE_PLUGIN_ROOT}/dist/index.js. A freshly cloned plugin without it will fail to start.

What the skill adds

The MCP server alone gives an agent the tools. The bundled skill gives it the judgement to use them well — and it costs one line of context until it fires:

• resolve approximate names with tibia_search before tibia_get
• modifiers are percentages where 100 is neutral, so a Dragon at modifier_fire: 0 is immune to fire, not weak to it
• hitpoints: null means unrecorded, not zero — 433 creatures have no recorded health
• imbuement.slots is a category list, not a count
• non-active pages are hidden unless include_inactive: true

Tools

Tool	Answers
tibia_search	"Is there a page called roughly X?"
tibia_get	"Tell me everything about X." — creature, item, NPC, quest or spell
tibia_find_creatures	"Which creatures match these stats?"
tibia_find_items	"Which items match these stats?"
tibia_how_to_obtain	"Where do I get X?" — drops, vendors and quest rewards in one call

Damage modifiers are percentages where 100 is neutral: above 100 the creature takes extra damage from that element. weak_to and resistant_to encode that for you.

Deprecated, event-only and unavailable pages are excluded by default; pass include_inactive: true to see them.

Refreshing

Re-run tibiawiki-mcp build-index. A failed rebuild never replaces a working index — the new one is validated before it is installed. Every tool response reports indexGeneratedAt, so staleness is always visible to whoever is asking.

The index lives at $TIBIAWIKI_MCP_DB, or ${XDG_CACHE_HOME:-~/.cache}/tibiawiki-mcp/tibiawiki.db.

Checking for upstream drift

Spell area shapes are decoded once and committed to data/spell-areas.json. To find out whether TibiaWiki has re-uploaded any of the source animations since:

pnpm decode-spell-areas <path-to-index.db> --check

It fetches metadata only, prints any image whose revision moved (and any new candidate the file has never seen), and exits non-zero if there is drift — so it can run on a schedule. Re-run without --check to regenerate.

Releases

Releases go to npm as @tibia.sh/tibiawiki-mcp, starting at 0.1.0.

The version number describes the server, not the data. The index it serves is a local snapshot you build yourself, so upgrading the package never refreshes it — see Refreshing.

The tarball ships exactly dist/ and data/spell-areas.json, plus the package.json, README.md and LICENSE npm always adds; npm pack --dry-run is the check that nothing else leaks in.

Attribution

Data from TibiaWiki (https://tibia.fandom.com), licensed CC BY-SA. Tibia is made by CipSoft; game content and images are copyright CipSoft GmbH.

The index is generated by tibiawiki-sql (Apache-2.0). Images are deliberately never fetched or stored.

This project's own code is MIT licensed; see LICENSE. That covers the code only — the data it serves is CC BY-SA and not ours to relicense.