Yahoo Fantasy Football MCP server for AI agents

Fantasy Football MCP Server is a comprehensive tool that leverages Model Context Protocol (MCP) to optimize Yahoo Fantasy Football teams. It provides intelligent lineup optimization, draft assistance, and league management through AI-powered analytics, combining data from multiple sources to deliver actionable insights for fantasy managers.

Features Overview

Core Capabilities

Multi-League Support for managing all Yahoo Fantasy Football leagues in your account
Player Enhancement Layer with intelligent projection adjustments
Lineup Optimization using advanced algorithms
Draft Assistant with real-time recommendations
Comprehensive Analytics including sentiment analysis
Multiple Deployment Options

Advanced Analytics

Position Normalization for smarter FLEX decisions
Multi-Source Projections combining expert rankings
Strategy-Based Optimization with different approaches
Volatility Scoring for floor vs ceiling analysis
Live Draft Support during active drafts

Player Enhancement Layer

This layer enriches player data with real-world context:

Bye Week Detection to prevent accidental starts
Recent Performance Stats showing trends from the last 1-3 weeks
Performance Flags including breakout candidates and declining roles
Adjusted Projections that blend recent performance with standard projections

Available Tools

League & Team Management

View leagues, standings, and team information
Analyze matchups and compare teams
Generate optimal lineups

Player Discovery

Browse available free agents
Find smart waiver wire targets
Access pre-draft rankings

Draft Assistant

Get AI-powered draft pick suggestions
Analyze draft state in real-time
Review post-draft results

Analytics

Analyze social media sentiment for players
Monitor API status and cache performance

Installation

git clone https://github.com/derekrbreese/fantasy-football-mcp-public.git
cd fantasy-football-mcp-public
pip install -r requirements.txt

Yahoo API Setup

Create a Yahoo Developer App at developer.yahoo.com
Note your Consumer Key and Consumer Secret
Complete OAuth flow using included scripts

Configuration

Create a .env file with your Yahoo API credentials:

YAHOO_CONSUMER_KEY=your_consumer_key_here
YAHOO_CONSUMER_SECRET=your_consumer_secret_here
YAHOO_ACCESS_TOKEN=your_access_token
YAHOO_REFRESH_TOKEN=your_refresh_token
YAHOO_GUID=your_yahoo_guid

Initial Authentication

# First-time setup
python setup_yahoo_auth.py

# Or manual authentication
python reauth_yahoo.py

Deployment Options

Local Development (FastMCP)

python fastmcp_server.py

Connect via HTTP transport at http://localhost:8000

Claude Code Integration (Stdio)

python fantasy_football_multi_league.py

Docker Deployment

docker build -t fantasy-football-mcp .
docker run -p 8080:8080 --env-file .env fantasy-football-mcp

Advanced Configuration

Strategy Weights

{
    "yahoo": 0.40,     # Yahoo expert projections
    "sleeper": 0.40,   # Sleeper expert rankings
    "matchup": 0.10,   # Defensive matchup analysis
    "trending": 0.05,  # Player trending data
    "momentum": 0.05   # Recent performance
}

Draft Strategies

Conservative: Prioritize proven players, minimize risk
Aggressive: Target high-upside breakout candidates
Balanced: Optimal mix of safety and ceiling potential

Troubleshooting

Common Issues

Authentication Errors

# Refresh expired tokens (expire hourly)
python utils/refresh_token.py

# Full re-authentication if refresh fails
python reauth_yahoo.py

Only One League Showing

Verify YAHOO_GUID matches your Yahoo account
Ensure leagues are active for current season
Check team ownership detection in logs

Rate Limiting

Yahoo allows 1000 requests/hour
Server implements 900/hour safety limit
Use ff_get_api_status to monitor usage
Clear cache with ff_clear_cache if needed

Stale Data

Cache TTLs: Leagues (1hr), Standings (5min), Players (15min)
Force refresh with ff_clear_cache tool
Check last update times in ff_get_api_status

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "fantasy-football-mcp" '{"command":"python","args":["-m","fantasy_football_multi_league.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "fantasy-football-mcp": {
            "command": "python",
            "args": [
                "-m",
                "fantasy_football_multi_league.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "fantasy-football-mcp": {
            "command": "python",
            "args": [
                "-m",
                "fantasy_football_multi_league.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect