Apppublic

MCP-1st-Birthday/world-of-warcraft-guild-management-mcp-server

sourceHugging Facemitupdated 10mo agoView on Hugging Face

0likes

App README

WoW Guild Analytics MCP Server

A Model Context Protocol (MCP) server providing comprehensive World of Warcraft guild analytics. Built with FastMCP 2.0 for the MCP 1st Birthday Hackathon.

Overview

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

Data Pipeline Architecture:

—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
—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 (activity logging)

Installation

Prerequisites

—Python 3.13+
—Blizzard Battle.net API credentials (Get them here)
—Supabase account (for activity logging)

Local Setup

1.Clone the repository:

bash

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

1.Create and activate a virtual environment:

bash

python -m venv venv
source venv/bin/activate

1.Install dependencies:

bash

pip install -r requirements.txt

1.Configure environment variables:

bash

cp .env.example .env

1.Run the server:

bash

python -m app.server

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

Hugging Face Spaces Deployment

This MCP server is deployed on Hugging Face Spaces at: https://huggingface.co/spaces/MCP-1st-Birthday/world-of-warcraft-guild-management-mcp-server

Live MCP Endpoint:

https://mcp-1st-birthday-world-of-warcraft-guild-managem-8e3b6f4.hf.space/mcp

Claude Desktop Integration

For Hugging Face Spaces (Hosted):

json

{
  "mcpServers": {
    "wow-guild-analytics": {
      "url": "https://mcp-1st-birthday-world-of-warcraft-guild-managem-8e3b6f4.hf.space/mcp",
      "transport": "http"
    }
  }
}

For Local Development:

json

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

Environment Variables

Required

bash

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

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

Optional

bash

# 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:

python

# 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 (app/core/discord_token_verifier.py) that validates tokens by calling Discord's API and tracks users in Supabase.

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

Setup for Hugging Face Spaces

1.Create Discord Application at Discord Developer Portal
2.Navigate to OAuth2 settings
3.Add redirect URI: https://mcp-1st-birthday-world-of-warcraft-guild-managem-8e3b6f4.hf.space/auth/callback
4.Copy Client ID and Client Secret

1.Set Environment Variables in Space Settings: Go to your Space Settings > Variables and secrets, and add:

bash

   OAUTH_PROVIDER=discord
   OAUTH_BASE_URL=https://mcp-1st-birthday-world-of-warcraft-guild-managem-8e3b6f4.hf.space
   DISCORD_CLIENT_ID=your_discord_client_id
   DISCORD_CLIENT_SECRET=your_discord_client_secret

1.OAuth Scopes: Automatically requests identify and email from Discord

1.DNS Configuration: The Dockerfile is pre-configured to use Google DNS (8.8.8.8) to ensure Discord API connectivity from Hugging Face Spaces.

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

Setup for Local Development

For local development without OAuth:

bash

# .env file
OAUTH_PROVIDER=  # Leave empty to disable

Deployment

Hugging Face Spaces Deployment

This server is designed to run on Hugging Face Spaces using Docker SDK.

Deployment Steps:

1.Fork or create a new Space:
2.Go to https://huggingface.co/new-space
3.Choose Docker as the SDK
4.Set hardware to CPU Basic (free tier)

1.Configure environment variables in Space Settings > Variables and secrets:

bash

   # Required
   BLIZZARD_CLIENT_ID=your_client_id
   BLIZZARD_CLIENT_SECRET=your_client_secret
   SUPABASE_URL=your_supabase_url
   SUPABASE_SERVICE_KEY=your_service_key

   # Optional - OAuth
   OAUTH_PROVIDER=discord
   OAUTH_BASE_URL=https://your-space-subdomain.hf.space
   DISCORD_CLIENT_ID=your_discord_client_id
   DISCORD_CLIENT_SECRET=your_discord_client_secret

1.Push your code:

bash

   git remote add hf https://huggingface.co/spaces/YOUR-USERNAME/YOUR-SPACE-NAME
   git push hf main

1.Monitor deployment:
2.View logs in the Space's "Logs" tab
3.The server will start on port 7860 (Hugging Face default)
4.MCP endpoint will be available at /mcp

Key considerations for HF Spaces:

—The Dockerfile configures Google DNS (8.8.8.8) for external API connectivity
—OAuth redirect URI must match your Space's subdomain
—Logs are viewable in the Space's web interface

Local Docker Deployment

For local testing:

bash

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

MCP Tools Available

The server exposes 7 MCP tools for guild management and analytics:

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.

—Parameters: realm, game_version, include_status
—Use Case: Lookup realm information and status

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

5. `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

6. `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

7. `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 URLs

—Hugging Face Spaces: https://mcp-1st-birthday-world-of-warcraft-guild-managem-8e3b6f4.hf.space
—Local Development: http://localhost:8000

MCP Endpoint

—Path: /mcp
—Protocol: HTTP transport (FastMCP 2.0)
—Authentication: OAuth (Discord) - required on production, optional locally

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:

json

{
  "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
│   │   ├── comparison_tools.py       # Member comparison tools
│   │   ├── demographics_tools.py     # Demographics analysis
│   │   └── diagnostic_tools.py       # Diagnostic utilities
│   ├── services/
│   │   └── supabase_client.py        # Supabase integration
│   ├── core/
│   │   ├── auth.py                   # OAuth authentication
│   │   ├── config.py                 # Configuration management
│   │   ├── constants.py              # Game constants
│   │   └── discord_token_verifier.py # Discord token validation
│   ├── utils/
│   │   ├── datetime_utils.py         # Time utilities
│   │   ├── logging_utils.py          # Logging configuration
│   │   ├── namespace_utils.py        # WoW namespace handling
│   │   └── response_utils.py         # Response formatting
│   └── visualization/                # Chart generation (future)
├── requirements.txt                  # Python dependencies
├── Dockerfile                        # HF Spaces Docker config
└── README.md                         # Documentation

Data Architecture

Guild & Character Data:

—Source: Real-time Blizzard Battle.net API calls
—Guild Rosters: Up-to-date member data with optimized fetching
—Character Profiles: Detailed information including equipment, specs, achievements, and statistics
—Realm Information: Server status and connected realm lookups

Activity Logging:

—Storage: Supabase database
—Tracking: All MCP tool calls with OAuth user attribution
—Metadata: Request/response data, duration, and error tracking

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

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:

—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:

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

Acknowledgments

—Built with FastMCP by @jlowin
—Powered by Blizzard Battle.net API
—Deployed on Hugging Face Spaces
—Activity tracking via Supabase
—OAuth authentication via Discord

Roadmap

—[ ] Add additional authentication routes
—[ ] PvP arena statistics and rankings
—[ ] Discord bot integration

WoW Guild Analytics MCP Server

Overview

Features

Tech Stack

Installation

Prerequisites

Local Setup

Hugging Face Spaces Deployment

Claude Desktop Integration

Environment Variables

Required

Optional

OAuth Configuration with Discord

How It Works

Setup for Hugging Face Spaces

Setup for Local Development

Deployment

Hugging Face Spaces Deployment

Local Docker Deployment

MCP Tools Available

1. get_guild_member_list

2. get_character_details

3. get_realm_info

4. lookup_items

5. get_guild_raid_progression

6. compare_member_performance

7. get_guild_demographics

API Documentation

Base URLs

MCP Endpoint

Example MCP Tool Call

Development

Project Structure

Data Architecture

Monitoring & Logging

Rate Limits

Contributing

License

Support

Acknowledgments

Roadmap

1. `get_guild_member_list`

2. `get_character_details`

3. `get_realm_info`

4. `lookup_items`

5. `get_guild_raid_progression`

6. `compare_member_performance`

7. `get_guild_demographics`