azerothMCP

blinkysc/azerothMCP

3.3

If you are the rightful owner of azerothMCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

AzerothCore MCP Server provides AI assistants with read-only access to AzerothCore databases and wiki documentation, enabling AI-powered assistance for understanding game mechanics.

Tools
5
Resources
0
Prompts
0

AzerothCore MCP Server

A Model Context Protocol (MCP) server that provides AI assistants like Claude with read-only access to AzerothCore databases and wiki documentation. This enables AI-powered assistance for understanding creature scripts, SmartAI logic, database schemas, and game mechanics.

Key Features

Progressive Disclosure & Token Optimization

This MCP implements progressive disclosure patterns to minimize token usage:

  • Compacted data by default: Database queries return only essential fields (75-90% reduction)
  • Lazy-loaded reference data: SmartAI/condition type definitions loaded only when needed
  • Optional tools disabled: Wiki and source code search disabled by default (can enable via config)
  • Discovery layer: AI can explore tool categories on-demand rather than loading all documentation upfront

Result: 96-98% reduction in token usage compared to traditional MCP servers while maintaining full functionality.

Features

Database Tools

  • query_database - Execute read-only SQL queries against world, characters, or auth databases
  • get_table_schema - Retrieve table structure/column definitions
  • list_tables - List tables with optional pattern filtering

Creature/NPC Tools

  • get_creature_template - Get creature data (compacted by default, use full=True for all 61 fields)
  • search_creatures - Search creatures by name pattern
  • get_creature_with_scripts - Get creature template with associated SmartAI scripts (compacted)

SmartAI Tools

  • get_smart_scripts - Retrieve SmartAI scripts (compacted by default, use full=True for all 33 fields)
  • explain_smart_script - Get documentation for event/action/target types
  • trace_script_chain - Debug and visualize SmartAI execution flow, following links, timed action lists, and data triggers
  • get_smartai_source - Get actual C++ implementation from SmartScript.cpp for any event/action/target type
  • generate_sai_comments - Generate human-readable comments for existing creature/gameobject scripts
  • generate_comment_for_script - Generate a comment for a single new script row before inserting
  • generate_comments_for_scripts_batch - Generate comments for multiple script rows at once

Spell Lookup Tools

  • get_spell_name - Look up a spell name by ID from Keira3's offline database
  • lookup_spell_names - Batch lookup multiple spell names at once

Source Code Tools (Optional - Disabled by Default)

  • search_azerothcore_source - Search AzerothCore source code for patterns
  • read_source_file - Read specific source files from AzerothCore
  • Enable with ENABLE_SOURCE_CODE=true in .env

Wiki/Documentation Tools (Optional - Disabled by Default)

  • search_wiki - Search AzerothCore wiki documentation
  • read_wiki_page - Read specific wiki pages
  • Enable with ENABLE_WIKI=true in .env

Additional Entity Tools

  • get_gameobject_template / search_gameobjects - GameObject lookup (compacted by default, 36 → ~8 fields)
  • search_spells - Search spell_dbc by name or ID (disabled by default, for custom spells only)
  • get_quest_template / search_quests - Quest lookup (compacted by default, 105 → ~15 fields)
  • diagnose_quest - Comprehensive quest diagnostics (givers, enders, requirements, chain, conditions, breadcrumb detection, issues with fix hints)
  • get_item_template / search_items - Item lookup (compacted by default, 139 → ~12 fields)

Conditions Tools

  • get_conditions - Get conditions for a specific source (loot, gossip, quest, SmartAI, vendor, etc.)
  • explain_condition - Get documentation for condition source types and condition types
  • diagnose_conditions - Check conditions for broken references and common issues
  • search_conditions - Search for conditions by type or value

Waypoint Tools

  • get_waypoint_path - Get waypoint path data (compacted by default, 11 → ~4 fields)
  • get_creature_waypoints - Get all waypoint paths for a creature entry (compacted)
  • search_waypoint_paths - Find waypoint paths in the database
  • visualize_waypoints - Generate 2D PNG visualization of waypoints on terrain
  • visualize_waypoints_3d - Generate interactive 3D visualization with terrain (opens in browser)
    • Click waypoints to select, shift+click terrain to move
    • Accumulate changes and export all SQL statements at once
    • Shows nearby NPCs and GameObjects as landmarks

SOAP / Worldserver Command Tools

  • soap_execute_command - Execute any GM command on a running worldserver via SOAP
  • soap_server_info - Get server uptime, player count, and version info
  • soap_reload_table - Hot-reload database tables without server restart
  • soap_check_connection - Test SOAP connectivity and authentication

Packet Parser Tools (WowPacketParser Integration)

Targeted extraction from WowPacketParser sniff files. Designed for context-efficient analysis of large parsed files.

Navigation:

  • list_packet_types - List all opcodes in a parsed file with counts
  • search_packets - Find packets by opcode, entry ID, content, or packet range
  • get_packet_by_number - Get a specific packet by number
  • get_packets_around - Get context around a packet (packets before/after)

Structured Extraction:

  • extract_creature_queries - Extract creature template data from SMSG_QUERY_CREATURE_RESPONSE
  • extract_gameobject_queries - Extract gameobject data from SMSG_QUERY_GAMEOBJECT_RESPONSE
  • extract_quest_queries - Extract quest info from SMSG_QUERY_QUEST_INFO_RESPONSE
  • extract_monster_moves - Extract movement/waypoint data from SMSG_ON_MONSTER_MOVE
  • extract_chat_messages - Extract NPC says/yells/emotes from SMSG_CHAT
  • extract_spell_casts - Extract spell cast data from SMSG_SPELL_GO
  • extract_emotes - Extract emote animations from SMSG_EMOTE

Advanced:

  • parse_pkt_targeted - Run WowPacketParser on a .pkt file with filters (opcode, entry, packet limit)

Requirements

  • Python 3.10+
  • MySQL with AzerothCore databases
  • (Optional) Local copy of AzerothCore wiki

Installation

  1. Clone the repository (with submodules for Keira3 spell database):
git clone --recursive https://github.com/yourusername/azerothMCP.git
cd azerothMCP

If you already cloned without --recursive, initialize submodules:

git submodule update --init --recursive
  1. Create and activate a virtual environment:
python3 -m venv venv
source venv/bin/activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Create a .env file with your configuration:
# Database connection
DB_HOST=localhost
DB_PORT=3306
DB_USER=acore
DB_PASSWORD=acore

# Database names
DB_WORLD=acore_world
DB_CHARACTERS=acore_characters
DB_AUTH=acore_auth

# Read-only mode (default: true)
# Set to "false" to allow INSERT, UPDATE, DELETE queries
READ_ONLY=true

# Enable spell_dbc tool (default: false, for custom spells only)
ENABLE_SPELL_DBC=false

# Enable wiki search tools (default: false)
# Disabled by default to reduce token usage
ENABLE_WIKI=false

# Enable source code search tools (default: false)
# Disabled by default to reduce token usage
ENABLE_SOURCE_CODE=false

# Wiki documentation path (only needed if ENABLE_WIKI=true)
# Clone https://github.com/azerothcore/wiki to ~/wiki
WIKI_PATH=~/wiki/docs

# AzerothCore source path (only needed if ENABLE_SOURCE_CODE=true)
AZEROTHCORE_SRC_PATH=~/azerothcore

# MCP server port
MCP_PORT=8080

# Maps path for terrain visualization (optional)
# Point to your AzerothCore server's maps directory
MAPS_PATH=~/azerothcore/data/maps

# Visualization server (for remote access to 3D waypoint visualizations)
VIZ_HOST=localhost
VIZ_PORT=8888

# SOAP Configuration (optional - for live server commands)
# Requires SOAP.Enabled = 1 in worldserver.conf
SOAP_ENABLED=false
SOAP_HOST=127.0.0.1
SOAP_PORT=7878
SOAP_USERNAME=your_admin_account
SOAP_PASSWORD=your_account_password

# WowPacketParser Configuration (optional - for sniff analysis)
ENABLE_PACKET_PARSER=true
WPP_PATH=~/WowPacketParser/WowPacketParser/bin/Release
DOTNET_PATH=~/.dotnet/dotnet

Project Structure

azerothMCP/
├── main.py                      # Entry point
├── azerothmcp/                  # Main package
│   ├── __init__.py
│   ├── config.py                # Configuration (DB, paths, flags)
│   ├── db.py                    # Database connection & query execution
│   ├── map_parser.py            # AzerothCore .map file parser for terrain
│   └── tools/                   # MCP tool modules
│       ├── __init__.py          # Tool registration
│       ├── database.py          # Database query tools
│       ├── creatures.py         # Creature/NPC tools
│       ├── smartai.py           # SmartAI scripting tools
│       ├── source.py            # AzerothCore source code tools
│       ├── wiki.py              # Wiki documentation tools
│       ├── gameobjects.py       # GameObject tools
│       ├── quests.py            # Quest tools
│       ├── items.py             # Item tools
│       ├── spells.py            # Spell lookup tools
│       ├── soap.py              # SOAP worldserver command tools
│       ├── conditions.py        # Conditions table tools
│       ├── waypoints.py         # Waypoint visualization tools
│       └── packets.py           # WowPacketParser sniff analysis tools
├── sai_comment_generator.py     # Keira3 SAI comment generator
├── soap_client.py               # SOAP client for worldserver
└── keira3/                      # Keira3 submodule (spell database)

Usage

Running the Server

Start the MCP server:

source venv/bin/activate
python main.py

The server starts on http://localhost:8080/sse using Server-Sent Events (SSE) transport.

Connecting with Claude Desktop

Add to your Claude Desktop MCP configuration:

Linux: ~/.config/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "azerothcore": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Then restart Claude Desktop. The AzerothCore tools will be available in your conversations.

Connecting with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "azerothcore": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Example Prompts

Once connected, you can ask things like:

  • "What scripts does Hogger (entry 448) have?"
  • "Show me the creature_template schema"
  • "Search for creatures named 'Defias'"
  • "Explain SmartAI event type 4"
  • "Trace the script chain for creature 1234"
  • "Find quests related to Westfall"
  • "Generate comments for this SmartAI script"
  • "What spell is ID 17364?"

Wiki Setup (Optional)

To enable wiki search functionality, clone the AzerothCore wiki:

cd ~
git clone https://github.com/azerothcore/wiki.git

The server will search markdown files in ~/wiki/docs by default. Update WIKI_PATH in your .env if your wiki is in a different location.

SOAP Setup (Optional)

SOAP allows executing GM commands on a running worldserver. This enables live server management like reloading tables after database changes, checking server status, or managing accounts.

1. Enable SOAP in worldserver.conf

SOAP.Enabled = 1
SOAP.IP = "127.0.0.1"
SOAP.Port = 7878

2. Configure Environment Variables

The account must have administrator privileges (SEC_ADMINISTRATOR, gmlevel 3+):

SOAP_ENABLED=true
SOAP_HOST=127.0.0.1
SOAP_PORT=7878
SOAP_USERNAME=your_admin_account
SOAP_PASSWORD=your_account_password

Example SOAP Commands

Once configured, you can use prompts like:

  • "Check if the worldserver is running"
  • "Reload the creature_template table"
  • "Get server info"
  • "Execute command: lookup creature hogger"

Security

By default, the server operates in read-only mode. Only SELECT, SHOW, and DESCRIBE queries are permitted.

To enable write operations (INSERT, UPDATE, DELETE) for full automation:

READ_ONLY=false

Warning: Enabling write mode allows the AI to modify your database. Use with caution and ensure you have backups.

License

GNU GPL v2 - See

Related Projects