WoW Guild Analytics MCP Server

MCPServer FastMCP Python FastAPI Battle.net Redis Heroku Supabase

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

Clone the repository:

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

Create and activate a virtual environment:

python -m venv venv source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Configure environment variables:

cp .env.example .env

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

Create a Heroku app:

heroku create your-app-name

Add Redis addon:

heroku addons:create heroku-redis:mini

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

Deploy:

git push heroku main

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 Available

The server exposes 9 MCP tools for guild and economy analysis:

1. `get_guild_member_list`

Retrieve guild roster with sorting and filtering options.

Parameters: realm, guild_name, sort_by, limit, quick_mode, game_version
Use Case: Get overview of guild members, sorted by rank/level/name

2. `get_character_details`

Deep character inspection with equipment, specs, achievements, and statistics.

Parameters: realm, character_name, sections, game_version
Sections: profile, equipment, specializations, achievements, statistics, media, pvp, appearance, collections, titles, mythic_plus
Use Case: Detailed player analysis for recruitment or progression planning

3. `get_realm_info`

Retrieve realm status and connected realm ID for auction house queries.

Parameters: realm, game_version, include_status
Use Case: Lookup realm IDs before querying realm-specific auction houses

4. `lookup_items`

Batch item lookup by ID with detailed metadata.

Parameters: item_ids (int or list), game_version, detailed
Use Case: Get item names, quality, prices, and stats for market analysis

5. `get_market_data`

Current market prices for commodities or auction house items.

Parameters: market_type, realm, item_ids, include_trends, trend_hours, max_results, game_version
Market Types: commodities (region-wide), auction_house (realm-specific)
Use Case: Real-time market snapshots with optional historical trends

6. `analyze_market`

Find profitable trading opportunities or check economy snapshot health.

Parameters: operation, market_type, realm, min_profit_margin, check_hours, realms, max_results, game_version
Operations: opportunities (find deals), health_check (system status)
Use Case: Identify underpriced items or monitor data collection health

7. `get_guild_raid_progression`

Guild achievement data including raid progression.

Parameters: realm, guild_name, game_version
Use Case: Track guild raid progression and achievement milestones

8. `compare_member_performance`

Compare performance metrics across guild members.

Parameters: realm, guild_name, member_names, metric, game_version
Metrics: item_level, achievement_points, guild_rank
Use Case: Performance comparisons for raid team optimization

9. `get_guild_demographics`

Comprehensive demographic breakdown of guild composition.

Parameters: realm, guild_name, game_version, max_level_only
Use Case: Analyze guild composition by class, race, spec, faction, and item level

API Documentation

Base URL

Local: http://localhost:8000
Production: https://your-app-name.herokuapp.com

MCP Endpoint

Path: /mcp
Protocol: HTTP transport (FastMCP 2.0)
Authentication: Optional OAuth (Discord)

Health Check

curl http://localhost:8000/health

Example MCP Tool Call

Through Claude Desktop or any MCP client:

Get the member list for guild "Liquid" on Illidan realm

Claude will automatically call:

{ "tool": "get_guild_member_list", "arguments": { "realm": "illidan", "guild_name": "liquid", "sort_by": "guild_rank", "limit": 50, "game_version": "retail" } }

Development

Project Structure

mcp_wowconomics_server/ ├── app/ │ ├── server.py # Main MCP server │ ├── api/ │ │ ├── blizzard_client.py # Blizzard API client │ │ └── guild_optimizations.py # Optimized guild fetching │ ├── tools/ │ │ ├── guild_tools.py # Guild roster tools │ │ ├── member_tools.py # Character analysis tools │ │ ├── realm_tools.py # Realm lookup tools │ │ ├── item_tools.py # Item data tools │ │ ├── auction_tools.py # Market analysis tools │ │ ├── visualization_tools.py # Chart generation tools │ │ └── demographics_tools.py # Demographics analysis │ ├── services/ │ │ ├── activity_logger.py # Activity logging service │ │ ├── auction_aggregator.py # Auction data aggregation │ │ ├── market_history.py # Market history tracking │ │ ├── supabase_client.py # Supabase integration │ │ └── supabase_streaming.py # Real-time streaming │ ├── core/ │ │ ├── auth.py # OAuth authentication │ │ ├── constants.py # Game constants │ │ └── discord_token_verifier.py │ └── utils/ │ ├── datetime_utils.py # Time utilities │ ├── logging_utils.py # Logging configuration │ ├── namespace_utils.py # WoW namespace handling │ └── response_utils.py # Response formatting ├── requirements.txt ├── Procfile # Heroku configuration ├── .env.example # Environment template └── README.md

Caching Strategy

The server implements intelligent Redis caching:

Guild Rosters: 15-day cache with age tracking
Economy Snapshots: 30-day retention with hourly captures
Market Trends: Rolling 30-day historical data
Cache Keys: Namespaced by game version, region, and realm

Monitoring & Logging

Activity Logging (via Supabase):

All MCP tool calls logged with user tracking
OAuth user attribution (Discord)
Request/response metadata and duration tracking
Error tracking and debugging

Health Checks:

Redis connectivity status
Blizzard API rate limits
Supabase streaming status
Economy snapshot freshness

Rate Limits

Blizzard API:

100 requests per second (soft limit)
36,000 requests per hour (hard limit)
Automatic retry with exponential backoff via tenacity

Redis:

50 max connections
TLS support for Heroku Redis

Contributing

Contributions are welcome. Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit your changes
Push to the branch (git push origin feature/your-feature)
Open a Pull Request

License

MIT License - See LICENSE file for details

Support

For issues, questions, or feature requests:

Discord: Contact me
LinkedIn: Noah Mott
GitHub Issues: Open an issue

Acknowledgments

Built with FastMCP by Marvin AI
Powered by Blizzard Battle.net API
Deployed on Heroku
Activity tracking via Supabase

Roadmap

Add additional authentication routes
PvP arena statistics and rankings
Discord bot integration
Long-term collection and analysis of WoW commodities market for research