league-analysis-mcp-server 0.1.2

Model Context Protocol server for Yahoo Fantasy Sports API with advanced historical analysis and manager profiling

League Analysis MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with access to Yahoo Fantasy Sports data, including advanced historical analysis and manager profiling capabilities.

Features

🏈 Multi-Sport Support

• NFL (National Football League)
• NBA (National Basketball Association)
• MLB (Major League Baseball)
• NHL (National Hockey League)

📊 Current Season Data

• League information and settings
• Real-time standings
• Team rosters and lineups
• Weekly matchups and scoring
• Transaction history

📈 Historical Analysis

• Multi-season draft analysis - Track draft patterns and strategies over time
• Manager performance history - Comprehensive performance metrics across seasons
• Transaction pattern analysis - Trading behavior and partnership identification
• Season-to-season comparisons - League evolution and competitive balance trends

🧠 Advanced Analytics

• Draft strategy classification - Identify RB-heavy, Zero-RB, or balanced approaches
• Manager skill evaluation - Comprehensive skill scoring based on multiple metrics
• Trade likelihood prediction - Predict trade partnerships based on historical patterns
• Pattern recognition - Identify trends in manager behavior and league dynamics

⚡ Performance Features

• Smart caching - Historical data cached permanently, current data with TTL
• Rate limiting - Respects Yahoo API limits
• Error handling - Comprehensive error handling and logging
• Multi-season support - Access data from 2015+ seasons

Installation

Prerequisites

• Python 3.10+
• Yahoo Developer App credentials (setup will guide you)

🚀 Easy Installation (PyPI)

One-Command Install:

# Install and run directly with uvx (recommended)
uvx league-analysis-mcp-server

# Or install with pip
pip install league-analysis-mcp-server
league-analysis-mcp-server

# Or run with python
python -m league_analysis_mcp_server

First-time setup: After installation, the server will guide you through Yahoo API setup automatically.

🔧 Development Installation

From Source:

git clone <repository-url>
cd league-analysis-mcp
uv run python setup_complete.py

This automated script will:

• ✅ Install all dependencies
• ✅ Run comprehensive system tests
• ✅ Guide you through Yahoo OAuth setup
• ✅ Test the complete integration
• ✅ Provide usage instructions

🔑 Yahoo Developer App Setup

If using the PyPI installation, the server will automatically guide you through this setup on first run. For reference:

1. Create Yahoo App:

   • Go to Yahoo Developer Console
   • Create new app:
     • Application Type: Web Application
     • Home Page URL: http://localhost
     • Redirect URI(s): oob
   • Copy Consumer Key & Secret

2. The server handles the rest automatically!

Usage

Starting the Server

# PyPI Installation (recommended):
uvx league-analysis-mcp-server

# Or if installed with pip:
league-analysis-mcp-server

# Development/Source:
uv run python -m src.server

🔌 MCP Client Configuration

Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "league-analysis": {
      "command": "uvx",
      "args": ["league-analysis-mcp-server"]
    }
  }
}

Configuration file locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code

Add this to your Claude Code MCP configuration:

{
  "mcpServers": {
    "league-analysis": {
      "command": "uvx",
      "args": ["league-analysis-mcp-server"]
    }
  }
}

Continue.dev

Add this to your Continue config:

{
  "mcpServers": [
    {
      "name": "league-analysis",
      "command": ["uvx", "league-analysis-mcp-server"]
    }
  ]
}

Other MCP Clients

For any MCP-compatible client, use these connection details:

• Command: uvx
• Args: ["league-analysis-mcp-server"]
• Transport: stdio (default)
• No working directory needed!

🔧 Testing Your Connection

After adding to your MCP client:

1. Restart your MCP client (Claude Desktop, etc.)
2. Test the connection by asking:
   • "Can you get server info for the league analysis server?"
   • "List available seasons for NFL"
   • "What fantasy sports tools are available?"
3. Check server status with: get_server_info()

🚨 Troubleshooting MCP Connection

Common issues:

1. Server not found:

   • Check the file path in your config
   • Ensure UV is installed and in PATH
   • Verify the server starts manually: uv run python -m src.server

2. Authentication errors:

   • Run: uv run python utils/setup_yahoo_auth.py
   • Check your Yahoo Developer app settings

3. Permission issues:

   • Ensure your MCP client has permission to execute UV
   • Check working directory permissions

4. Environment variables:

   • MCP clients may not inherit your shell environment
   • Create .env file in project root with credentials

Available Tools

Basic League Tools

• get_server_info() - Server status and configuration
• get_setup_instructions() - Yahoo API setup help
• list_available_seasons(sport) - Available historical seasons
• get_league_info(league_id, sport, season?) - League settings and metadata
• get_standings(league_id, sport, season?) - Current or historical standings
• get_team_roster(league_id, team_id, sport, season?) - Team roster information
• get_matchups(league_id, sport, week?, season?) - Weekly matchup data

Historical Analysis Tools

• get_historical_drafts(league_id, sport, seasons?) - Draft results across seasons
• get_season_transactions(league_id, sport, season) - Transaction history for season
• analyze_manager_history(league_id, sport, seasons?, team_id?) - Manager performance patterns
• compare_seasons(league_id, sport, seasons) - Season-to-season analysis

Advanced Analytics Tools

• analyze_draft_strategy(league_id, sport, seasons?, team_id?) - Draft pattern analysis
• predict_trade_likelihood(league_id, sport, team1_id?, team2_id?, seasons?) - Trade predictions
• evaluate_manager_skill(league_id, sport, seasons?, team_id?) - Comprehensive skill evaluation

Cache Management

• clear_cache(cache_type?) - Clear cached data ('all', 'current', 'historical')

Available Resources

Access read-only data through these resource URIs:

• league_overview://sport/league_id[/season] - Comprehensive league overview
• current_week://sport/league_id - Current week activity and focus areas
• league_history://sport/league_id - Multi-season history and trends
• manager_profiles://sport/league_id[/team_id] - Manager profiling information

Example Usage

# Get basic league info
result = get_league_info("123456", "nfl")

# Analyze manager performance across last 3 seasons  
analysis = analyze_manager_history("123456", "nfl", ["2022", "2023", "2024"])

# Get draft strategies for all managers
draft_analysis = analyze_draft_strategy("123456", "nfl", ["2022", "2023", "2024"])

# Evaluate manager skill levels
skill_eval = evaluate_manager_skill("123456", "nfl", ["2022", "2023", "2024"])

# Predict trade likelihood between specific managers
trade_pred = predict_trade_likelihood("123456", "nfl", "team1", "team2")

Configuration

Game IDs

The server includes game ID mappings for seasons 2015-2024 across all supported sports. These are automatically used when specifying historical seasons.

Caching Strategy

• Historical data: Cached permanently (TTL = -1)
• Current season data: Cached for 5 minutes (TTL = 300)
• Cache size: Limited to 100MB by default

Rate Limiting

• Default: 60 requests per minute
• Burst limit: 10 requests
• Automatically handled by the server

Architecture

Core Components

• FastMCP 2.0: High-level MCP framework for rapid development
• YFPY: Yahoo Fantasy Sports API wrapper
• Caching Layer: Smart caching for performance optimization
• Authentication Manager: OAuth handling for Yahoo API access
• Analytics Engine: Advanced pattern recognition and predictions

Data Flow

1. Request → Authentication → Cache Check → Yahoo API → Response Processing → Cache Storage → Response
2. Historical Data: Cached permanently after first fetch
3. Current Data: Cached with TTL, automatically refreshed

Error Handling

• Comprehensive error logging
• Graceful degradation for missing data
• Cache fallback for API failures
• User-friendly error messages

Supported Analysis Types

Manager Profiling

• Performance Tiers: Elite, Above Average, Average, Below Average, Needs Improvement
• Consistency Scoring: Win rate, scoring, and ranking consistency
• Success Patterns: Championship rate, playoff appearances, trajectory analysis

Draft Strategy Classification

• RB-Heavy: Prioritizes running backs in early rounds
• Zero-RB: Waits on running backs, focuses on WR/other positions
• Balanced: Even distribution across position types
• Auction Analysis: Spending patterns and value identification

Trade Pattern Analysis

• Partnership Identification: Historical trade frequency between managers
• Likelihood Scoring: Probability of future trades based on history
• Trade Timing: Seasonal patterns and deadline behavior

Troubleshooting

Common Issues

1. Authentication Error

   • Verify Yahoo Consumer Key/Secret in .env
   • Check app configuration in Yahoo Developer Console
   • Run get_setup_instructions() for detailed setup help

2. No Historical Data

   • Ensure league has existed for multiple seasons
   • Verify correct league ID and sport combination
   • Check game ID mappings in config/game_ids.json

3. Cache Issues

   • Use clear_cache("all") to reset all cached data
   • Check cache statistics with get_server_info()

4. Rate Limiting

   • Server automatically handles rate limits
   • Historical data queries may take longer due to multiple API calls
   • Use caching to minimize repeated requests

Support

For issues and feature requests, please check the documentation or create an issue in the project repository.

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read the contributing guidelines and submit pull requests for any improvements.