Tibia MCP Server

A tool that downloads, parses, and indexes all content from TibiaWiki — the wiki for the MMORPG Tibia — and serves it via an MCP (Model Context Protocol) server for AI agents.

Quick Start

The fastest way to get everything running is with Claude Code (Anthropic's official CLI). This project includes a custom skill /start that automates the entire setup:

1. Open a terminal at the project root

2. Start Claude Code: claude

3. Run the skill:

/start

The skill will automatically:

1. Check all prerequisites (Docker, Docker Compose, free ports, etc.)

2. Create the persistent data directory for PostgreSQL

3. Start the database, run the crawler, and launch the MCP server

4. Display the ready-to-use MCP URL

MCP URL: http://localhost:8000/sse

Prerequisites

• Claude Code installed (npm install -g @anthropic-ai/claude-code)

• Docker and Docker Compose V2

• Ports 5432 (PostgreSQL) and 8000 (MCP) available

Persistent Data

PostgreSQL data is stored in ./data/postgres/ on the host machine. This means restarting containers does not lose data — the crawler doesn't need to re-download everything.

Useful Commands

# Watch logs in real-time
docker compose logs -f

# Check service status
docker compose ps

# Stop everything (data preserved)
docker compose down

# Full reset (deletes data)
docker compose down -v && rm -rf ./data/postgres && docker compose up --build -d

MCP Configuration for Claude Desktop

Add to your MCP configuration file:

{
  "mcpServers": {
    "tibiawiki": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Related MCP server: mcp-web-calc

What It Does

1. Downloads all TibiaWiki pages via the MediaWiki API (raw wikitext)

2. Parses structured infoboxes from 20 entity types (creatures, items, spells, NPCs, quests, etc.)

3. Stores normalized data in PostgreSQL

4. Extracts map coordinates and generates tags/summaries per entity

5. Serves the data via MCP with 19 tools optimized for AI agent queries

Stack

• Python 3.12

• PostgreSQL 16 — relational storage with materialized views

• FastMCP — MCP server for AI agent integration

• Docker + Docker Compose — containerized environment

• psycopg2, requests, python-dotenv

• pgvector + llama-index (optional) — semantic search via embeddings

Project Structure

src/
  main.py           # Orchestrator (runs all 6 phases)
  mcp_server.py     # MCP server with 19 tools
  tagger.py         # Tag and summary generation
  api/              # HTTP client with rate limiting and retry
  parser/           # Parsers by infobox type (20 types)
  db/               # Connection, migrations, and upserts

migrations/         # 28 numbered SQL files
tests/              # pytest + wikitext fixtures
web/                # Next.js landing page

How It Works

src/main.py runs 6 sequential phases:

Phase 0 → Migrations          Apply SQL migrations to the database
Phase 1 → Download            Download wikitext from all pages (batches of 50)
Phase 2 → Parse & Import      Extract infoboxes and upsert into normalized tables
Phase 3 → Positions           Extract {{mapa|X,Y,Z}} coordinates to the positions table
Phase 4 → Tags & Summaries    Generate tags (e.g. "boss", "immune_fire") and text summaries
Phase 5 → Materialized Views  Refresh creature_drops, npc_trades, quest_bosses, etc.

Supported Entities

MCP Server

src/mcp_server.py exposes 19 tools for AI agents to query the database. The suggested usage pattern is:

discover → filter → detail

Tools

Usage Examples

Real questions an AI agent can answer using this MCP:

Equipment recommendation by vocation and level

"What's the recommended set for a Knight level 400?"

The agent uses items_for_vocation("knight") filtering by each slot (helmet, armor, legs, boots, shield, ring) and cross-references with level to build the best combination:

Complete quest guide

"How do I complete the Desert Quest?"

The agent uses search("desert quest", entity_type="quests") followed by get_entity("quests", "The Desert Dungeon Quest") to return the full spoiler: preparation, required items, step-by-step path, sacrifice room positioning, and rewards.

NPC locations

"Where are the guards for the Inquisition Quest?"

The agent fetches each NPC with get_entity("npcs", "Walter, The Guard") etc., returning exact coordinates and TibiaWiki map links:

More examples

• "Creatures weak to fire?" → creature_weakness("fire")

• "Where does Falcon Longsword drop?" → where_to_get_item("Falcon Longsword")

• "Best hunts for Paladin level 250?" → recommend_hunt(250, "paladin")

• "Most expensive items?" → rank_entities("items", "npc_value")

• "Dragon Lord vs Frost Dragon?" → compare_creatures("Dragon Lord", "Frost Dragon")

• "Where to sell Demon Helmet?" → where_to_sell_item("Demon Helmet")

• "Profit per kill at Hydra?" → profit_analysis("Hydra")

Local Setup (without Docker)

# 1. Copy and edit the configuration file
cp .env.example .env

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the downloader
python -m src.main

# 4. Start the MCP server
python -m src.mcp_server

Tests

pytest tests/

Fixtures in tests/fixtures/ contain real wikitext samples for testing parsers.

Semantic Search (optional)

To enable semantic search with embeddings:

1. Install the optional dependencies in requirements.txt (uncomment the llama-index lines)

2. Make sure the pgvector extension is enabled in PostgreSQL (migration 027_enable_pgvector.sql)

3. Run python -m src.indexer after the download