WoW Guild Analytics MCP Server

                <a href="https://discord.com/users/479379710766481436"><img alt="Discord" src="https://img.shields.io/badge/Discord-%235865F2.svg?&style=flat&logo=discord&logoColor=white" /></a>  <a href="https://linkedin.com/in/noahmott"><img alt="LinkedIn" src="https://img.shields.io/badge/linkedin%20-%230077B5.svg?&style=flat&logo=linkedin&logoColor=white"/></a> 

A Model Context Protocol (MCP) server providing comprehensive World of Warcraft guild analytics, auction house data, and market insights through the Blizzard Battle.net API. Built with FastMCP 2.0 and deployed on Heroku.

Overview

This MCP server integrates with Claude Desktop (or any MCP client) to provide real-time WoW guild management, player analysis, and auction house economics data. It supports both Retail and Classic WoW with proper namespace handling, Redis caching for performance, and optional Supabase logging for user activity tracking.

Features

• Guild Management: Retrieve guild rosters, member details, and raid progression data
• Character Analysis: Deep character inspection including equipment, specializations, achievements, and statistics
• Auction House Economics: Real-time commodity and auction house data with trend analysis
• Market Intelligence: Identify profitable trading opportunities and track price trends
• Demographics Analytics: Comprehensive guild demographic breakdowns by class, race, spec, and item level
• Realm Information: Server status and connected realm ID lookup
• Item Lookup: Batch item data retrieval with detailed metadata
• Visualization: Raid progress tracking and member performance comparisons
• Redis Caching: Optimized response times with intelligent cache management
• OAuth Authentication: Discord OAuth integration for user tracking
• Activity Logging: Supabase integration for usage analytics and monitoring

Tech Stack

Core Framework:

• Python 3.13
• FastAPI 0.116.1
• FastMCP 2.0+ (Model Context Protocol)
• Uvicorn/Gunicorn (ASGI server)

Data & Caching:

• Redis 6.2 (caching and performance optimization)
• Supabase (activity logging and user tracking)
• SQLAlchemy 2.0 (database operations)

Installation

Prerequisites

• Python 3.13+
• Redis server (local or Heroku Redis)
• Blizzard Battle.net API credentials (Get them here)
• Supabase account (optional, for activity logging)

Local Setup

1. Clone the repository:

git clone https://github.com/noahmott/mcp_wowconomics_server.git
cd mcp_wowconomics_server

1. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate 

1. Install dependencies:

pip install -r requirements.txt

1. Configure environment variables:

cp .env.example .env

1. Run the server:

python -m app.server

The server will start on http://localhost:8000 with the MCP endpoint at /mcp.

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "wow-guild-analytics": {
      "url": "http://localhost:8000/mcp",
      "transport": "http"
    }
  }
}

For production (Heroku):

{
  "mcpServers": {
    "wow-guild-analytics": {
      "url": "https://your-app-name.herokuapp.com/mcp",
      "transport": "http"
    }
  }
}

Environment Variables

Required

# Blizzard API Credentials (REQUIRED)
BLIZZARD_CLIENT_ID=your_blizzard_client_id_here
BLIZZARD_CLIENT_SECRET=your_blizzard_client_secret_here

# Redis Configuration (REQUIRED)
REDIS_URL=redis://localhost:6379      # Local development
# Heroku automatically sets REDIS_URL for rediss://... (TLS)

Optional

# OAuth Authentication (Optional)
OAUTH_PROVIDER=                       # Options: discord (empty = disabled)
OAUTH_BASE_URL=http://localhost:8000  # Your server's public URL
DISCORD_CLIENT_ID=                    # Discord OAuth credentials
DISCORD_CLIENT_SECRET=

# Supabase (Optional - Activity Logging)
SUPABASE_URL=                         # Your Supabase project URL
SUPABASE_SERVICE_KEY=                 # Service role key (bypasses RLS)

# Server Configuration
PORT=8000
HOST=0.0.0.0
DEBUG=false

# Feature Flags
ENABLE_REDIS_CACHING=true
ENABLE_SUPABASE_LOGGING=true
ENABLE_AI_ANALYSIS=true

# API Timeouts (seconds) Necessary for reducing API traffick to Blizzard
API_TIMEOUT_TOTAL=300
API_TIMEOUT_CONNECT=10
API_TIMEOUT_READ=60

Deployment

Heroku Deployment

1. Create a Heroku app:

heroku create your-app-name

1. Add Redis addon:

heroku addons:create heroku-redis:mini

1. Set environment variables:

heroku config:set BLIZZARD_CLIENT_ID=your_client_id
heroku config:set BLIZZARD_CLIENT_SECRET=your_client_secret
heroku config:set BLIZZARD_REGION=us
heroku config:set WOW_VERSION=retail

1. Deploy:

git push heroku main

1. Verify deployment:

heroku logs --tail

The server will automatically use the REDIS_URL environment variable set by the Heroku Redis addon.

Docker Deployment (Alternative)

docker build -t wow-mcp-server .
docker run -p 8000:8000 --env-file .env wow-mcp-server

MCP Tools Ava…