<p align="center"> <img src="https://img.shields.io/badge/version-0.5.0-blue" alt="Version"> <img src="https://img.shields.io/badge/python-3.10+-green" alt="Python"> <img src="https://img.shields.io/badge/license-MIT-orange" alt="License"> <img src="https://img.shields.io/badge/tools-60+-purple" alt="Tools"> </p>

EQEmu MCP Server

Give your AI assistant full context on your EverQuest Emulator server — source code, quest API, database schema, documentation, and live game data — so it can write accurate queries, debug issues, and manage content without guessing.

A Model Context Protocol (MCP) server for EverQuest Emulator servers. Works with Windsurf, VS Code, Cursor, OpenAI Codex, Claude Desktop, and any MCP-compatible AI client.

---

What's Included

Your AI assistant gets access to everything it needs to understand and operate your EQEmu server:

| Data Source | What Your AI Can Access | |---|---| | 📚 EQEmu Documentation | Full-text search across all 638 pages of docs.eqemu.io — server operation guides, configuration references, quest tutorials, and more | | 🗄️ Database Schema Docs | Detailed documentation for all 261 tables across 48 categories — column names, types, descriptions, and ER relationship diagrams | | 🔍 Live Database | Read-only SQL queries against your actual game database — NPCs, items, spawns, loot, characters, accounts, zones, spells, factions, tasks, tradeskills | | 💻 C++ Source Code | Full-text search across the EQEmu C++ codebase — find how mechanics work, trace calculations, understand game systems | | 📜 Quest Scripts | Browse and search all Perl/Lua quest scripts across every zone — read quest logic, find event handlers, trace quest flows | | 🔧 Quest API Reference | Complete Lua and Perl quest API documentation — method signatures, event lists, and examples for all 30+ method classes | | ⚙️ Server Configuration | Server rules, content flags, expansion settings, eqemu_config.json (with passwords auto-redacted) | | 📋 Server Logs | Recent server logs and crash logs for debugging | | 👤 Characters & Accounts | Character inspection (stats, AAs, inventory, guild), account details, IP history, alt/multibox detection | | 🗺️ Zone Details | Zone information with spawn counts, NPC lists, doors/portals, ground spawns, forage/fishing tables, patrol grids | | Development Context | Structured environment diagnostics, reusable debugging workflows, and quest/entity investigation prompts |

No guessing. Your AI looks up the exact schema, follows the correct relationships, and writes accurate queries on the first try.

---

Why?

When you ask an AI assistant to write a query, inspect spawn data, or debug a quest issue, it has to guess table names, column names, relationships, and valid values. It gets things wrong. You end up copy-pasting schema docs and correcting hallucinated SQL.

This MCP server eliminates that. Your AI assistant can:

• Look up exact schema — get_schema_doc("npc_types") returns all 80+ columns with types and descriptions
• Follow relationships — table_relationships("spawn2") shows FK links through the entire spawn chain
• Search documentation — search_docs("loottable_id") finds every doc page referencing that column
• Query live data — run_query("SELECT * FROM npc_types WHERE name LIKE '%Nagafen%'") hits your actual database
• Inspect full chains — NPC → faction → loot → spawn group → grid path, all from structured tools

The result: correct queries on the first try, accurate quest scripts, and faster debugging.

---

Tools (60+)

Read-Only (always available)

| Category | Tools | Description | |---|---|---| | C++ Source | search_source get_source_file list_source_files | Search and browse the EQEmu C++ codebase | | Quest API | list_quest_api_classes get_quest_api_methods | Browse Lua/Perl quest API method signatures | | Quest Scripts | list_quest_zones list_quest_files read_quest_file search_quests | Browse and search quest scripts across all zones | | Server Files | list_server_files read_server_file get_server_config | Server files, plugins, config (passwords redacted) | | Server Info | get_server_rules get_server_logs get_crash_logs get_content_flags get_expansion_info | Rules, logs, crash analysis, content flags | | Database | list_tables describe_table run_query table_relationships | Schema inspection and read-only SQL | | NPCs | search_npcs get_npc | NPC search by name/zone/level with spawn locations | | Items | search_items get_item search_items_by_stat | Item search by name/type/level or stat thresholds | | Spawns | get_zone_spawns get_spawngroup | Spawn points, spawn groups, placeholder/named setups | | Loot | get_npc_loot | Full loot chain: NPC → loottable → lootdrop → items | | Merchants | get_merchant_items | Merchant inventories | | Zones | search_zones get_zone_info | Zone lookup with spawn/NPC/door counts | | Spells | search_spells get_spell | Spell search and full effect/class breakdown | | Factions | search_factions get_npc_faction | Faction search and NPC faction kill-hit details | | Tasks | search_tasks get_task | Task search and full activity/reward breakdown | | Characters | list_characters get_character get_online_characters | Character inspection, stats, AAs, inventory, online players | | Accounts | get_account_info find_associated_accounts | Account investigation, IP history, alt detection | | Tradeskills | search_recipes get_recipe | Recipe search and component/result breakdown | | Grids | get_npc_grid | NPC patrol paths with waypoint coordinates | | Doors | get_zone_doors | Zone doors/portals with destinations, keys, lockpick | | Ground Spawns | get_ground_spawns | Clickable ground items in a zone | | Forage/Fishing | get_zone_forage_fishing | Zone forage and fishing loot tables | | Documentation | search_docs read_doc list_doc_sections | Full-text search across docs.eqemu.io | | Schema Docs | get_schema_doc list_schema_tables | Table docs with column descriptions and ER relationships | | Quest API Docs | get_quest_api_doc | Official quest API docs with signatures and examples | | Server Docs | get_server_doc | Server operation guides and command references | | Development | inspect_development_environment | Structured status for source, quest, server, docs, and database inputs |

The server also publishes eqemu://development/workflows and the debug_quest and trace_entity prompts. MCP 2026-07-28 clients receive structured output schemas and read/write/destructive behavior annotations for every tool.

Write Tools (opt-in)

Enable with EQEMU_ACCESS_MODE=readwrite:

| Category | Tools | Description | |---|---|---| | Quest Editing | write_quest_file delete_quest_file | Create, edit, or delete quest scripts | | Server Rules | set_server_rule | Change server rule values | | Content Flags | set_content_flag | Enable/disable content flags | | NPC Management | create_npc update_npc | Create or modify NPCs | | Spawn Management | create_spawn delete_spawn | Add/remove spawn points | | Loot Management | add_loot_to_npc | Add items to NPC loot tables | | Merchants | add_merchant_item remove_merchant_item | Manage merchant inventories | | Data Buckets | get_data_buckets set_data_bucket | Read/write data buckets | | Database | run_write_query | Execute INSERT/UPDATE/DELETE queries |

---

Quick Start

Upgrading from 0.4

Version 0.5 uses MCP SDK 2 and the 2026-07-28 protocol. Docker and --http now serve Streamable HTTP at /mcp. Update remote client URLs from /sse to /mcp; --sse remains available for legacy clients.

For an existing akk-stack Docker installation:

cd /opt/akk-stack/eqemu-mcp-server
git pull --ff-only
cd /opt/akk-stack
docker compose -f docker-compose.yml \
  -f eqemu-mcp-server/docker-compose.akk-stack.yml \
  build eqemu-mcp
docker compose -f docker-compose.yml \
  -f eqemu-mcp-server/docker-compose.akk-stack.yml \
  up -d --no-deps eqemu-mcp

For an existing manual installation:

cd /opt/akk-stack/eqemu-mcp-server
git pull --ff-only
source ../eqemu-mcp-venv/bin/activate
pip install -e .
sudo systemctl restart eqemu-mcp  # only when installed as a service

Prerequisites

• Python 3.10+
• Access to an EQEmu server (akk-stack recommended)
• ripgrep (optional — for fast source code search, falls back to grep)

Option A: Docker (Recommended)

git clone https://github.com/straps-eq/eqemu-mcp-server.git
cd eqemu-mcp-server

cp .env.example .env
# Edit .env with your database credentials and paths

docker compose up -d

The server starts on port 8888. Connect your MCP client to http://YOUR_SERVER_IP:8888/mcp.

akk-stack Integration

If you're running akk-stack, the MCP server can join your existing Docker network and talk to MariaDB directly. No separate .env file is needed — the compose overlay reads credentials from your akk-stack .env automatically.

Step 1: Clone into your akk-stack directory

cd /opt/akk-stack
git clone https://github.com/straps-eq/eqemu-mcp-server.git

Step 2 (optional): Add token authentication

To require a token for connections, add this to your akk-stack .env:

echo "EQEMU_MCP_TOKEN=$(openssl rand -hex 32)" >> /opt/akk-stack/.env
# View the generated token:
grep EQEMU_MCP_TOKEN /opt/akk-stack/.env

Step 3: Build and start the MCP container

cd /opt/akk-stack

# Build the image
docker compose -f docker-compose.yml \
  -f eqemu-mcp-server/docker-compose.akk-stack.yml \
  build eqemu-mcp

# Start (only the MCP container — does NOT restart your game server)
docker compose -f docker-compose.yml \
  -f eqemu-mcp-server/docker-compose.akk-stack.yml \
  up -d --no-deps eqemu-mcp

⚠️ Important: Always use --no-deps eqemu-mcp to start only the MCP container. Without --no-deps, Docker Compose may recreate your MariaDB and EQEmu server containers, causing a server restart.

Step 4: Open the firewall

sudo ufw allow 8888/tcp

Step 5: Verify

docker logs akk-stack-eqemu-mcp-1 --tail 5
# Should show: "Uvicorn running on http://0.0.0.0:8888"

The MCP server is read-only by default. It automatically:

• Connects to MariaDB via the backend network (no external IP needed)
• Mounts your code/ and server/ directories read-only
• Uses your existing MARIADB_PASSWORD from the akk-stack .env

Configuration: All settings go in your akk-stack .env (/opt/akk-stack/.env) — you do not create a separate .env inside the eqemu-mcp-server/ folder. Available variables:

| Variable | Default | Description | |---|---|---| | MARIADB_PASSWORD | (from akk-stack) | Database password — already in your .env | | IP_ADDRESS | 0.0.0.0 | Bind address — already in your .env | | EQEMU_DB_NAME | peq | Database name — set this if your DB isn't named peq | | EQEMU_DB_USER | eqemu | Database user — set to a read-only user for extra safety (see Read-Only DB User) | | EQEMU_DB_PASSWORD | ${MARIADB_PASSWORD} | Database password — override if using a separate read-only user | | EQEMU_MCP_TOKEN | (empty) | Set to require token auth on connections | | MCP_ACCESS_MODE | read | Set to readwrite to enable write tools |

Option B: Manual Install (No Docker)

git clone https://github.com/straps-eq/eqemu-mcp-server.