# Sleeper MCP Server

A Model Context Protocol (MCP) server that provides Claude Desktop with access to Sleeper Fantasy Football API data. This server enables users to query league information, player data, matchups, and draft results through natural language interactions with Claude.

## Features

- **League Management**: Query leagues, rosters, users, and league settings
- **Draft Analysis**: Complete draft results with pick positions, keeper status, and team attribution
  - Full draft history with all rounds and picks
  - Player draft metadata showing original draft position and team
  - Keeper identification with 🔒 indicators
  - Free agent tracking for undrafted players
- **Player Information**: Search players, get statistics, and trending data
- **Matchup Analysis**: View current and historical matchups with real-time scoring
- **Intelligent Caching**: Optimized API usage with TTL-based caching
- **Rate Limiting**: Respects Sleeper API limits with exponential backoff

## Installation

### Prerequisites

- Python 3.10 or higher
- Claude Desktop application

### Install from Source

1. Clone the repository:
```bash
git clone <repository-url>
cd sleeper-mcp-server
```

2. Install the package:
```bash
pip install -e .
```

3. For development with testing and linting tools:
```bash
pip install -e ".[dev]"
```



## Configuration

### Claude Desktop MCP Configuration

Add the following configuration to your Claude Desktop MCP settings file:

**Location of config file:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Basic Configuration:**
```json
{
  "mcpServers": {
    "sleeper": {
      "command": "python",
      "args": ["-m", "sleeper_mcp_server"],
      "disabled": false,
      "autoApprove": [
        "get_user_leagues",
        "get_league_info",
        "search_players",
        "get_trending_players",
        "get_nfl_state"
      ]
    }
  }
}
```

**Auto-approving every tool:**
```json
{
  "mcpServers": {
    "sleeper": {
      "command": "python",
      "args": ["-m", "sleeper_mcp_server"],
      "disabled": false,
      "autoApprove": [
        "get_user_leagues",
        "get_league_info",
        "get_league_rosters",
        "get_league_rosters_with_draft_info",
        "get_league_users",
        "get_roster_user_mapping",
        "get_league_draft",
        "search_players",
        "get_trending_players",
        "get_player_stats",
        "get_matchups",
        "get_matchup_scores",
        "get_nfl_state"
      ]
    }
  }
}
```

## Available MCP Tools

### League Tools

#### `get_user_leagues`
Get all leagues for a username in a specific season.

**Parameters:**
- `username` (required): Sleeper username to look up
- `season` (optional): Season year (defaults to current season)

**Example Usage:**
```
Show me all leagues for username "john_doe"
Show me all leagues for username "john_doe" in 2025
```

#### `get_league_info`
Get detailed information about a specific league.

**Parameters:**
- `league_id` (required): League ID to retrieve information for

**Example Usage:**
```
Get information for league ID "123456789"
```

#### `get_league_rosters`
Get all team rosters in a league.

**Parameters:**
- `league_id` (required): League ID to retrieve rosters for

**Example Usage:**
```
Show me all rosters in league "123456789"
```

#### `get_league_users`
Get all users/participants in a league.

**Parameters:**
- `league_id` (required): League ID to retrieve users for

**Example Usage:**
```
Who are the users in league "123456789"?
```

#### `get_league_rosters_with_draft_info`
Get all team rosters in a league with complete draft position metadata for each player.

**Parameters:**
- `league_id` (required): League ID to retrieve rosters for

**Example Usage:**
```
Show me all rosters with draft information for league "123456789"
```

#### `get_roster_user_mapping`
Get a clear mapping of roster IDs to user names for a league.

**Parameters:**
- `league_id` (required): League ID to get roster-user mapping for

**Example Usage:**
```
Show me the roster to user mapping for league "123456789"
```

#### `get_league_draft`
Get complete draft results and pick information for a league.

**Parameters:**
- `league_id` (required): League ID to get draft information for

**Example Usage:**
```
Show me the draft results for league "123456789"
```

### Player Tools

#### `search_players`
Search for players by name with optional position filtering.

**Parameters:**
- `query` (required): Player name or partial name to search for
- `position` (optional): Position filter (QB, RB, WR, TE, K, DEF)

**Example Usage:**
```
Search for players named "Josh Allen"
Find all quarterbacks with "Josh" in their name
```

#### `get_trending_players`
Get trending players (most added/dropped).

**Parameters:**
- `sport` (optional): Sport type (default: "nfl")
- `add_drop` (optional): Type of trend - "add" or "drop" (default: "add")

**Example Usage:**
```
Show me the most added players this week
What players are being dropped the most?
```

#### `get_player_stats`
Get player statistics for a specific season and optional week.

**Parameters:**
- `player_id` (required): Player ID to get stats for
- `season` (optional): Season year (defaults to current season)
- `week` (optional): Week number within the season

**Example Usage:**
```
Get stats for player ID "4046"
Get stats for player ID "4046" in week 5
```

### Matchup Tools

#### `get_matchups`
Get matchups for a specific week in a league.

**Parameters:**
- `league_id` (required): League ID to retrieve matchups for
- `week` (required): Week number (1-22)

**Example Usage:**
```
Show me week 5 matchups for league "123456789"
```

#### `get_matchup_scores`
Get real-time scoring information for matchups in a specific week.

**Parameters:**
- `league_id` (required): League ID to retrieve scores for
- `week` (required): Week number (1-22)

**Example Usage:**
```
What are the current scores for week 8 in league "123456789"?
```

### State Tools

#### `get_nfl_state`
Get the current NFL state including season, week, and season type.

**Parameters:**
- None

**Example Usage:**
```
What's the current NFL week?
What season are we in?
```

## API Rate Limiting and Caching

### Rate Limiting

The server implements intelligent rate limiting to respect Sleeper API guidelines:

- **Rate Limit**: Follows Sleeper's documented rate limits
- **Retry Logic**: Exponential backoff (1s, 2s, 4s, 8s) for rate-limited requests
- **Queue Management**: Requests are queued during rate limit periods
- **User Feedback**: Clear messages when rate limits are encountered

### Caching Strategy

Different data types have optimized cache TTL values:

| Data Type | Cache TTL | Reason |
|-----------|-----------|---------|
| Player Data | 1 hour | Relatively static during season |
| League Settings | 24 hours | Rarely change mid-season |
| Draft Data | 24 hours | Historical data, doesn't change |
| Matchup Data (active) | 5 minutes | Real-time scoring updates |
| Matchup Data (completed) | 1 hour | Historical data is stable |
| Trending Players | 30 minutes | Updated frequently |
| Roster Data | 15 minutes | Changes with transactions |
| Roster Data (with draft) | 15 minutes | Changes with transactions |

**Cache Features:**
- In-memory caching for optimal performance
- TTL-based expiration
- Automatic cache invalidation
- Cache hit/miss logging for monitoring

## Usage Examples

### Basic League Queries

```
# Get your leagues
"Show me all leagues for username 'myusername'"

# Get league details
"What are the settings for league ID '123456789'?"

# View rosters
"Show me all the rosters in my main league"

# View rosters with draft information
"Show me all rosters with draft info - I want to see where each player was drafted and by whom"
```

### Player Research

```
# Search for players
"Find all players named 'Cooper'"

# Get trending players
"What players are being added the most this week?"

# Player statistics
"Show me Josh Allen's stats"
"Show me Josh Allen's stats for week 5"
```

### Matchup Analysis

```
# Current week matchups
"What are this week's matchups in my league?"

# Live scoring
"What are the current scores for week 8?"

# Historical data
"Show me the results from week 3"
```

### Draft Analysis

```
# Complete draft results
"Show me the draft results for my league"

# Roster with draft info
"Show me all rosters with draft information - I want to see where each player was drafted"

# Keeper analysis
"Which players were kept from last year and what was their original draft cost?"

# Draft value analysis
"Show me players who are outperforming their draft position"
```

## Troubleshooting

### Common Issues

#### 1. Server Won't Start

**Symptoms:**
- Claude Desktop shows "Server unavailable" error
- No response from MCP tools

**Solutions:**
- Verify Python installation: `python --version` (should be 3.10+)
- Check package installation: `pip show sleeper-mcp-server`
- Verify Claude Desktop configuration syntax
- Check logs for specific error messages

#### 2. Authentication/API Errors

**Symptoms:**
- "API request failed" errors
- "Invalid league ID" messages

**Solutions:**
- Verify league IDs are correct (18-character strings)
- Check username spelling and case sensitivity
- Ensure Sleeper API is accessible from your network
- Try again after a few minutes (may be temporary API issues)

#### 3. Rate Limiting Issues

**Symptoms:**
- "Rate limit exceeded" messages
- Slow response times
- "Please wait" messages

**Solutions:**
- Wait for the specified retry period
- Reduce frequency of requests
- Use cached data when possible
- Check if multiple instances are running

#### 4. Cache Issues

**Symptoms:**
- Stale data being returned
- Inconsistent results

**Solutions:**
- Restart the MCP server to clear cache
- Adjust the TTL constants in `sleeper_mcp_server/cache.py`
- Check system memory availability

#### 5. Configuration Problems

**Symptoms:**
- Tools not appearing in Claude Desktop

**Solutions:**
- Validate JSON syntax in Claude Desktop config
- Restart Claude Desktop after configuration changes
- Check file permissions on config file

### Logging

The server logs to stderr at `INFO`. The level is set in `sleeper_mcp_server/__main__.py`;
there is no environment-variable override.

### Getting Help

1. **Check Logs**: Read the server's stderr output for detailed error information
2. **Verify Configuration**: Ensure Claude Desktop MCP configuration is correct
3. **Test API Access**: Verify you can access Sleeper API directly
4. **Update Dependencies**: Ensure all packages are up to date
5. **Restart Services**: Try restarting both the MCP server and Claude Desktop

### Performance Optimization

#### For Large Leagues
- Use position filtering in player searches
- Cache frequently accessed league data
- Limit historical matchup queries

#### For Multiple Leagues
- Batch similar requests when possible
- Use appropriate cache TTL settings
- Monitor rate limit usage

## Development

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=sleeper_mcp_server

# Run specific test file
pytest tests/test_server.py
```

### Code Quality

```bash
# Format code
black sleeper_mcp_server/

# Sort imports
isort sleeper_mcp_server/

# Lint code
flake8 sleeper_mcp_server/

# Type checking
mypy sleeper_mcp_server/
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- [Sleeper API](https://docs.sleeper.app/) for providing comprehensive fantasy football data including detailed draft information
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP framework
- [Claude Desktop](https://claude.ai/desktop) for MCP integration

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Review existing GitHub issues
3. Create a new issue with detailed information about your problem

---

**Note**: This MCP server is not officially affiliated with Sleeper. It's a third-party integration that uses Sleeper's public API.