Fork notice: This is a personal fork of carterfawson/fantasy-football-mcp, itself derived from derekrbreese/fantasy-football-mcp-public. Git history was rewritten to remove credential files the upstream author had committed. Runtime deps are pinned in requirements-runtime.txt / requirements-lock.txt.

Enhanced Fantasy Football MCP Server

A Model Context Protocol (MCP) server for Yahoo Fantasy Football integration with Claude Desktop. Features advanced lineup optimization, draft assistance, comprehensive league management, and enhanced roster management capabilities.

🙏 Attribution

This project is based on the excellent foundation provided by derekrbreese/fantasy-football-mcp-public. Special thanks to Derek Breese for the initial concept, architecture, and scaffolding that made this enhanced version possible.

Related MCP server: Yahoo Fantasy Baseball MCP

✨ Enhancements in This Fork

• Enhanced Roster Management: Fixed "position already filled" errors with intelligent position change detection

• Working Waiver Wire Transactions: Fully functional add/drop player capabilities with proper Yahoo API integration

• Waiver Status Tracking: New function to monitor pending waiver claims and their approval status

• Single-Player Position Changes: Safer lineup management that changes one player at a time

• Improved Error Handling: Comprehensive response parsing and detailed debugging information

• Fixed Import Dependencies: Resolved sleeper_api and other module import issues

• Yahoo API Compliance: Updated XML formatting to match Yahoo's exact specifications

Features

• Multi-League Support: Manage all your Yahoo Fantasy Football leagues

• AI-Powered Optimization: Advanced lineup recommendations with multiple strategies

• Draft Assistant: Real-time draft recommendations and analysis

• Waiver Wire Analysis: Find top pickups with trending data

• Position Normalization: Smart FLEX decisions with position-adjusted scoring

• Rate Limiting & Caching: Efficient API usage with built-in optimization

Quick Start

Prerequisites

• Python 3.9+

• Claude Desktop

• Yahoo Fantasy Sports account

• Yahoo Developer App credentials

Installation

1. Clone the repository:

git clone https://github.com/carterfawson/fantasy-football-mcp.git
cd fantasy-football-mcp

2. Install dependencies:

pip install -r requirements.txt

3. Configure API credentials:

   • Yahoo API: Follow YAHOO_SETUP.md for detailed setup

   • Reddit API (optional): See REDDIT_SETUP.md for player sentiment analysis

   • Copy .env.example to .env

   • Add your API credentials

   • Run authentication: python utils/setup_yahoo_auth.py

4. Configure Claude Desktop:

   • Add the MCP server configuration (see INSTALLATION.md)

   • Restart Claude Desktop

Available MCP Tools

League Management

• ff_get_leagues - List all your fantasy football leagues

• ff_get_league_info - Get detailed league information

• ff_get_standings - View current standings

Team Management

• ff_get_roster - Get your team roster

• ff_get_matchup - View matchup details with opponent analysis

• ff_get_opponent_roster - Get opponent's roster for matchup planning

• ff_get_opponent_roster_comparison - Detailed roster comparison and insights

• ff_get_optimal_lineup - Get AI lineup recommendations

🆕 Enhanced Roster Management

• ff_set_lineup - Set your starting lineup (enhanced with intelligent position change detection)

• ff_change_player_position - Move a single player to a different position (safer than full lineup changes)

• ff_add_player - Add players from free agents or waiver wire (fully functional)

• ff_drop_player - Drop players from your roster

• ff_get_waiver_status - Check status of pending waiver claims and transactions

Player Discovery

• ff_get_players - Browse available players

• ff_get_waiver_wire - Find top waiver pickups

• ff_get_draft_rankings - Get pre-draft rankings

Draft & Admin

• ff_get_draft_results - View draft results

• ff_get_draft_recommendation - Get live draft advice

• ff_refresh_token - Refresh Yahoo access token

Project Structure

fantasy-football-mcp-public/
├── fantasy_football_multi_league.py  # Main MCP server
├── src/                               # Core modules
│   ├── agents/                        # Specialized agents
│   ├── models/                        # Data models
│   ├── strategies/                    # Lineup strategies
│   └── utils/                         # Utility functions
├── utils/                             # Authentication utilities
├── config/                            # Configuration
└── requirements.txt                   # Dependencies

Configuration

See INSTALLATION.md for detailed setup instructions.

Security

• Never commit .env files or API credentials

• See SECURITY.md for security policy

• Regularly rotate access tokens

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - See LICENSE file

Support

For issues or questions, please use the GitHub Issues page.