world_of_warcraft_mcp_server

noahmott/world_of_warcraft_mcp_server

3.2

If you are the rightful owner of world_of_warcraft_mcp_server 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.

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.

Tools
9
Resources
0
Prompts
0

WoW Guild Analytics MCP Server

MCPServer  FastMCP  Python  FastAPI  n8n  Battle.net  Heroku  Supabase     

A Model Context Protocol (MCP) server providing comprehensive World of Warcraft guild analytics and commodity market insights. Built with FastMCP 2.0 and deployed on Heroku with n8n data collection pipeline.

Overview

This MCP server integrates with Claude Desktop (or any MCP client) to provide real-time WoW guild management, player analysis, and commodity market economics data.

Data Pipeline Architecture:

  • Commodity Market Data: Automated n8n workflows pull from Blizzard API hourly → Store in Supabase → MCP queries database (10-100x faster than API)
  • Guild & Character Data: Direct Blizzard API calls for real-time data
  • Activity Tracking: All MCP tool usage logged to Supabase with Discord OAuth user attribution

Features

  • Guild Management: Retrieve guild rosters, member details, and raid progression data
  • Character Analysis: Deep character inspection including equipment, specializations, achievements, and statistics
  • Commodity Market Economics: Real-time commodity pricing data (ore, herbs, reagents) with historical trend analysis
  • Market Intelligence: Identify profitable trading opportunities with price variance analysis
  • 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
  • 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 Storage:

  • Supabase (commodity market data storage and activity logging)
  • n8n (automated commodity data collection from Blizzard API)

Installation

Prerequisites

  • Python 3.13+
  • Blizzard Battle.net API credentials (Get them here)
  • Supabase account (for commodity market data and 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

# Supabase Configuration (REQUIRED for commodity data)
SUPABASE_URL=                         # Your Supabase project URL
SUPABASE_SERVICE_KEY=                 # Service role key (bypasses RLS)

Optional

# OAuth Authentication (see OAuth Configuration section for setup)
OAUTH_PROVIDER=discord               # Options: discord (empty = disabled)
OAUTH_BASE_URL=http://localhost:8000 # Your server's public URL
DISCORD_CLIENT_ID=                   # From Discord Developer Portal
DISCORD_CLIENT_SECRET=               # From Discord Developer Portal

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

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

OAuth Configuration with Discord

This server uses FastMCP's OAuthProxy for Discord authentication, which automatically handles the OAuth flow including authorization, token exchange, and validation. When enabled, all MCP tool calls are attributed to Discord users and logged in Supabase for activity tracking.

How It Works

FastMCP OAuthProxy creates OAuth endpoints automatically when passed to the MCP server:

# app/core/auth.py
auth_provider = OAuthProxy(
    upstream_authorization_endpoint="https://discord.com/api/oauth2/authorize",
    upstream_token_endpoint="https://discord.com/api/oauth2/token",
    upstream_client_id=DISCORD_CLIENT_ID,
    upstream_client_secret=DISCORD_CLIENT_SECRET,
    base_url=OAUTH_BASE_URL,
    token_verifier=DiscordTokenVerifier()
)

mcp = FastMCP("WoW Guild Analytics MCP", auth=auth_provider)

This automatically creates:

  • /oauth/authorize - Initiates Discord OAuth flow
  • /oauth/callback - Handles Discord's redirect after authentication
  • /oauth/token - Token exchange for MCP clients

Custom Token Verification: Discord uses opaque tokens (not JWTs), so we implement a custom DiscordTokenVerifier () that validates tokens by calling Discord's API and tracks users in Supabase.

Activity Logging: The with_supabase_logging decorator () extracts the Bearer token, verifies it with Discord, looks up the user in Supabase, and logs all tool calls with full user attribution.

Setup

  1. Create Discord Application at Discord Developer Portal

    • Navigate to OAuth2 settings
    • Add redirect URI: https://your-app-name.herokuapp.com/oauth/callback
    • Copy Client ID and Client Secret

  2. Set Environment Variables:

OAUTH_PROVIDER=discord
OAUTH_BASE_URL=https://your-app-name.herokuapp.com
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
  1. OAuth Scopes: Automatically requests identify and email from Discord

To disable OAuth: Leave OAUTH_PROVIDER empty and activity logs will record as "anonymous"

Deployment

Heroku Deployment

  1. Create a Heroku app:
heroku create your-app-name
  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
heroku config:set SUPABASE_URL=your_supabase_url
heroku config:set SUPABASE_SERVICE_KEY=your_service_key
  1. Deploy:
git push heroku main
  1. Verify deployment:
heroku logs --tail

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 commodity market prices (ore, herbs, reagents, etc.) from Supabase.

  • Parameters: item_ids, include_trends, trend_hours, max_results, region
  • Data Source: Supabase (collected via n8n from Blizzard API)
  • Use Case: Real-time region-wide commodity market snapshots with optional historical trends

6. analyze_market

Find profitable commodity trading opportunities or check data collection health.

  • Parameters: operation, min_profit_margin, max_results, region
  • Operations: opportunities (find deals), health_check (check n8n data freshness)
  • Use Case: Identify commodities with high price variance or monitor data pipeline 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
│   │   ├── comparison_tools.py    # Member comparison tools
│   │   └── demographics_tools.py  # Demographics analysis
│   ├── services/
│   │   ├── activity_logger.py     # Activity logging service
│   │   ├── auction_aggregator.py  # Auction data aggregation
│   │   ├── 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

Data Architecture

Commodity Market Data (via n8n + Supabase):

  • Collection: n8n workflow pulls from Blizzard API hourly
  • Storage: Supabase commodity_auctions table
  • Retention: Configurable (90+ days supported based on storage)
  • Performance: Direct database queries - much faster than API calls

Guild & Character Data (via Blizzard API):

  • Guild Rosters: Real-time API calls for up-to-date member data
  • Character Data: Real-time API calls with detailed profile information

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:

  • Blizzard API rate limits
  • Supabase connectivity status
  • Commodity data freshness (n8n workflow health)

Rate Limits

Blizzard API:

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

Supabase:

  • Database queries for commodity data
  • Activity logging with Discord OAuth attribution

Contributing

Contributions are welcome. Please follow these guidelines:

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

License

MIT License - See LICENSE file for details

Support

For issues, questions, or feature requests:

Acknowledgments

Roadmap

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