Sleeper Fantasy MCP

A Model Context Protocol (MCP) server for integrating Sleeper Fantasy Football with Claude Code. Get comprehensive fantasy analytics, player projections, historical performance, and league management directly through Claude.

Features

🏈 Complete Fantasy Analytics

Real-time player projections and historical scores
Advanced NFL metrics (snap counts, target share, efficiency stats)
Waiver wire analysis and trending players
Lineup optimization and matchup projections

📊 Comprehensive Player Data

Passing: completions, attempts, passer rating, air yards, sacks
Rushing: YPC, broken tackles, yards after contact, red zone carries
Receiving: catch rate, target share, drops, air yards, YAC
Snap counts and usage percentages

🎯 Fantasy Tools

Historical scoring (actual fantasy points vs projections)
League standings and matchup analysis
Available players and waiver wire gems
Trending players with add/drop activity

Quick Setup

1. Install Dependencies

npm install

2. Configure Your Leagues

Copy the example environment file and add your Sleeper information:

cp .env.example ~/.env

Edit ~/.env with your details:

SLEEPER_USERNAME=your_sleeper_username
ROAD_TO_GLORY_ID=your_league_id_1  
DYNASTY_LEAGUE_ID=your_league_id_2
ROAD_TO_GLORY_TEAM=Your Team Name 1
DYNASTY_TEAM=Your Team Name 2

Finding Your League ID:

Open Sleeper app/website
Go to your league
Copy the long number from the URL (e.g., 1199118916182364160)

3. Build the Project

npm run build

4. Add to Claude Code

Add this to your Claude Code MCP configuration in ~/.claude.json:

{
  "mcpServers": {
    "sleeper-fantasy": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sleeper-fantasy-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Replace /path/to/sleeper-fantasy-mcp with the actual path to this directory.

5. Restart Claude Code

Exit and restart Claude Code to load the new MCP server.

Available Tools

Core Fantasy Tools

get_league_info - League settings and standings
get_my_roster - Your current roster with player details
get_my_matchup - Current week matchup analysis
get_available_players - Waiver wire and free agents

Advanced Analytics

get_player_projections - Projected fantasy points
get_historical_scores - Actual historical performance with advanced stats
get_matchup_projections - Compare projected vs opponent
optimize_lineup - Optimal lineup suggestions

Research Tools

get_trending_players - Hot waiver wire pickups
Player filtering by position, team, availability
Advanced metrics like snap counts, target share, efficiency

Example Usage

"What were Jalen Hurts' actual stats in Week 1?"
"Who are the trending RBs I should pick up?"  
"Optimize my lineup for this week"
"Show me my current matchup projections"
"Find available WRs with high target share"

Advanced Configuration

Multiple Leagues

You can configure up to 2 leagues (modify config.ts for more). Set league names in the environment:

ROAD_TO_GLORY_ID / ROAD_TO_GLORY_TEAM
DYNASTY_LEAGUE_ID / DYNASTY_TEAM

API Settings

SLEEPER_API_BASE - Sleeper API endpoint (default: https://api.sleeper.app/v1)
CACHE_DURATION_MINUTES - Cache duration for API calls (default: 15)

Development

Project Structure

src/
├── index.ts              # Main MCP server
├── config.ts             # Configuration management
└── tools/                # Individual MCP tools
    ├── LeagueTool.ts     # League information
    ├── RosterTool.ts     # Roster management  
    ├── ProjectionsTool.ts # Player projections
    ├── HistoricalScoresTool.ts # Historical performance
    └── ...

Building

npm run build    # Build TypeScript
npm run watch    # Watch mode for development
npm run start    # Run the server

Testing

npm test        # Verify build works

Troubleshooting

"League not found" errors

Verify your league ID is correct (copy from Sleeper URL)
Check that your username matches your Sleeper profile
Ensure team name matches exactly (case sensitive)

MCP connection issues

Restart Claude Code after configuration changes
Check the path to dist/index.js is correct
Verify the project built successfully (npm run build)

No data returned

Confirm you're in an active fantasy season
Check that your leagues are public or you're a member
Verify week numbers are valid (1-18)

Contributing

Feel free to submit issues and enhancement requests!

License

MIT License - see LICENSE file for details.