Content
# EverQuest MCP
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides AI assistants with comprehensive access to EverQuest game data. Search across 12 online databases, lore/archive sources, and a local game data installation with **412 tools** covering spells, items, NPCs, zones, quests, factions, achievements, overseer, mercenaries, lore, archives, and more.
## Features
- **412 tools** for querying EverQuest data
- **Multi-source search** — Query 12 online EQ databases, lore sources, and archive sources in parallel
- **Local game data** — Parse 70K+ spells, 1600+ factions, 2700+ AAs, 800+ overseer quests, and more directly from game files
- **Deep spell analysis** — Effects, categories, stacking, class comparisons, efficiency rankings, burst/sustained DPS, flexible multi-parameter queries
- **Character data** — Race/class info, skill caps, base stats, AC mitigation, deities, Drakkin heritages
- **Creature encyclopedia** — 980+ NPC/monster race types searchable by name
- **Overseer system** — Agents with archetypes/traits/jobs, quests with slot details and success/failure outcomes
- **Zone maps** — 34K+ points of interest from Brewall map files, zone search by name/level, teleport spell lookup
- **Patch diff detection** — Snapshot game data before a patch, then compare after to see exactly what changed
- **Quest guides** — Epic quest walkthroughs, leveling guides, farming guides
## Data Sources
### Local Game Data
The primary data source, powering 386 of the 412 tools. The server parses EverQuest game files directly to provide authoritative, offline access to the full game database:
- **70K+ spells** with effects, classes, categories, stacking rules, and cast messages
- **1600+ factions** with starting values by race, class, and deity
- **2700+ AA abilities** with ranks, descriptions, and spell correlations
- **800+ overseer quests** and 300+ agents with traits, jobs, and slot requirements
- **4200+ mercenary templates** with stances, tiers, and abilities
- **34K+ map points of interest** from Brewall map files
- **980+ creature/NPC race types**, 550+ in-game events, 50+ lore stories
- **Achievement system**, skill caps, base stats, AC mitigation tables, and more
Data is parsed on demand and cached in memory. No external network calls required.
### Online Databases, Lore, and Archives
External EQ community databases and historical lore/archive sources searched via web scraping, MediaWiki APIs, and bounded archive-search API calls. These provide quest guides, item databases, raid loot tables, original lore, and community-maintained or preserved content not available in local game files.
| Source | Specialty |
|--------|-----------|
| [Allakhazam](https://everquest.allakhazam.com) | Primary online database — spells, items, NPCs, zones |
| [Almar's Guides](https://www.almarsguides.com/eq) | Quest walkthroughs, epic guides, leveling |
| [EQ Traders](https://www.eqtraders.com) | Tradeskill recipes and guides |
| [EQInterface](https://www.eqinterface.com) | UI mods, maps, parsers, and tools |
| [EQResource](https://eqresource.com) | Modern expansion content, progression |
| [Fanra's Wiki](https://everquest.fanra.info) | General game information, mechanics |
| [Lucy](https://lucy.allakhazam.com) | Classic EQ spell and item data (historical) |
| [RaidLoot](https://raidloot.com/EQ) | Raid loot tables by expansion |
| [Zliz's Compendium](https://www.zlizeq.com) | Comprehensive EQ encyclopedia |
| [Official Sony EQ History (Wayback)](https://web.archive.org/web/19990910004532/http://everquest.station.sony.com/e_history.html) | Original official 1999 History of Norrath lore page |
| [The Firiona Vie Project Lore](https://fvproject.com/index.php/Category:Lore) | Classic EverQuest lore category via MediaWiki API |
| [EQArchives](https://search.eqarchives.org/) | Preserved EQ websites, mailing lists, patch records, logs, screenshots, and historical corpus search |
## Installation
```bash
git clone https://github.com/ArtSabintsev/everquest1-mcp.git
cd everquest1-mcp
npm install
npm run build
```
### Local Game Data (Optional)
For offline access to comprehensive game data, set the `EQ_GAME_PATH` environment variable to your EverQuest installation directory. On macOS with CrossOver:
```json
{
"mcpServers": {
"everquest": {
"command": "node",
"args": ["/absolute/path/to/everquest1-mcp/dist/index.js"],
"env": {
"EQ_GAME_PATH": "/path/to/EverQuest"
}
}
}
}
```
Without this, only online database tools are available.
## Configuration
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"everquest": {
"command": "node",
"args": ["/absolute/path/to/everquest1-mcp/dist/index.js"]
}
}
}
```
Then restart Claude Desktop.
## Available Tools (412)
| Category | Tools | Description |
|----------|------:|-------------|
| [Online Search](docs/tools-online-search.md) | 21 | Multi-source search across 9 EQ databases |
| [Spells & Abilities](docs/tools-spells.md) | 276 | Lookup, search, per-class profiles, efficiency analysis, cross-class comparisons, global statistics |
| [Character & Classes](docs/tools-character-classes.md) | 60 | Race/class/deity info, skill caps, base stats, AC mitigation, creature types |
| [Zones & Maps](docs/tools-zones-maps.md) | 14 | Zone search, map POIs, teleport network, leveling guide |
| [Factions & Currencies](docs/tools-factions-currencies.md) | 18 | 1600+ factions, alternate currencies, tributes, deity-faction optimization |
| [Achievements & AAs](docs/tools-achievements-aas.md) | 16 | Achievement lookup, AA abilities, category browsing |
| [Overseer](docs/tools-overseer.md) | 10 | 300+ agents, 800+ quests, trait/job optimization |
| [Mercenaries](docs/tools-mercenaries.md) | 7 | 4200+ templates, stances, tier analysis, class synergy |
| [Items & Effects](docs/tools-items-effects.md) | 8 | 1100+ item click/proc effects, augmentation system |
| [Lore, Reference & Patch Detection](docs/tools-lore-reference.md) | 35 | Lore stories, expansions, events, help topics, patch diff detection, FVProject lore, EQArchives search |
## Example Queries
Once configured, you can ask your AI assistant things like:
- "What does the spell Complete Heal do?"
- "Show me all Cleric resurrection spells"
- "What are the Wizard fire spells at level 65?"
- "Find all spells with a stun effect for Enchanter"
- "How do I start the bard epic 1.0 quest?"
- "What are the best leveling spots for level 70-80?"
- "Tell me about the faction Wolves of the North"
- "What overseer quests are available for plunder?"
- "Search EQArchives for Miragul"
- "Read the FVProject lore page Innoruuk (Lore)"
- "Show the official History of Norrath"
- "Show me map locations in Plane of Knowledge near the bank"
- "What AA abilities are available for Shaman?"
- "What are the most mana-efficient Wizard nukes?"
- "Compare burst damage between Wizard and Magician"
- "Which spells are exclusive to Bard?"
## Development
```bash
npm run dev # Build and run
npm run build # Build only
npm run test # Run tests
npm start # Run built version
```
## Architecture
```
src/
├── index.ts # MCP server entry point
├── tools.ts # Tool definitions and handlers (412 tools)
├── sources/ # Data source implementations
│ ├── base.ts # Shared interfaces and fetch utilities
│ ├── index.ts # Source aggregation
│ ├── localdata.ts # Local EQ game file parser (40K+ lines)
│ ├── allakhazam.ts # Allakhazam scraper
│ ├── almars.ts # Almar's Guides
│ ├── eqresource.ts # EQResource
│ ├── fanra.ts # Fanra's Wiki (MediaWiki API)
│ ├── eqtraders.ts # EQ Traders
│ ├── zliz.ts # Zliz's Compendium
│ ├── lucy.ts # Lucy spell/item database
│ ├── raidloot.ts # RaidLoot raid drops
│ ├── eqinterface.ts # EQInterface UI mods
│ └── historiclore.ts # Official EQ history, FVProject lore, EQArchives
└── tests/ # Test suite
└── tools.test.ts
```
## Local Game Data Files Parsed
When `EQ_GAME_PATH` is set, the server parses these game files on demand:
| File | Data |
|------|------|
| `spells_us.txt` | 70K+ spells with effects, classes, categories |
| `spells_us_str.txt` | Spell cast messages |
| `dbstr_us.txt` | AA names, spell descriptions, faction names, overseer data, events, expansions, creature types (980+), starting city lore, and 40+ other string types |
| `eqstr_us.txt` | Game UI strings, deity lore |
| `Resources/skillcaps.txt` | Skill cap data by class/level |
| `Resources/basedata.txt` | Base stat progression |
| `Resources/ACMitigation.txt` | AC mitigation tables |
| `Resources/SpellStackingGroups.txt` | Spell stacking rules |
| `Resources/ZoneNames.txt` | Zone names and short names |
| `Resources/Achievements/` | Achievement definitions, categories, components |
| `Resources/Faction/` | Faction data, categories, starting values |
| `Resources/OvrMini*` | Overseer agent data, traits, images |
| `Resources/OvrQst*` | Overseer quest data, slots, trait groups |
| `Resources/OvrJobClient.txt` | Overseer job types |
| `Resources/bannercategories.txt` | Guild banner categories |
| `Resources/campsitecategories.txt` | Fellowship campsite categories |
| `Resources/playercustomization.txt` | Drakkin heritage data (6 dragon lineages) |
| `maps/` | Brewall/standard zone map files (34K+ POIs) |
| `Help/` | 75 official in-game help topic HTML files |
## Adding New Sources
1. Create a new file in `src/sources/` implementing the `EQDataSource` interface
2. Export it from `src/sources/index.ts`
3. Add to the `sources` array for multi-source search
4. Optionally add source-specific tools in `src/tools.ts`
## License
MIT
