# sleeper-mcp

An MCP (Model Context Protocol) server for the [Sleeper](https://sleeper.com) Fantasy Sports API. Gives Claude, Cursor, VS Code Copilot, and any other MCP-compatible AI client read access to Sleeper's public API — no API key required.

## What you can do

Ask your AI assistant things like:

- *"What leagues am I in this season?"* (give it your Sleeper username)
- *"Show me the standings and rosters for my league"*
- *"Who won the championship bracket?"*
- *"What trades happened this week?"*
- *"Which players are being added the most right now?"*
- *"Show me all first-round draft picks from my 2024 draft"*

## Available Tools

| Tool | Description |
|------|-------------|
| `sleeper_get_user` | Look up a user's profile by username or user ID |
| `sleeper_get_nfl_state` | Current NFL week, season type, and season year |
| `sleeper_get_user_leagues` | All leagues a user is in for a given sport/season |
| `sleeper_get_league` | Full league details including scoring and roster settings |
| `sleeper_get_league_rosters` | All rosters with win/loss records and player lists |
| `sleeper_get_league_users` | All managers in a league with their team names |
| `sleeper_get_league_matchups` | Weekly matchup scores for any week |
| `sleeper_get_league_winners_bracket` | Playoff championship bracket |
| `sleeper_get_league_losers_bracket` | Consolation / toilet bowl bracket |
| `sleeper_get_league_transactions` | Trades, waiver claims, and FA adds/drops by week |
| `sleeper_get_league_traded_picks` | All traded draft picks in a league |
| `sleeper_get_user_drafts` | All drafts a user participated in |
| `sleeper_get_league_drafts` | All drafts for a league |
| `sleeper_get_draft` | Full draft details (type, order, slot mapping) |
| `sleeper_get_draft_picks` | Every pick in a draft with player and position info |
| `sleeper_get_draft_traded_picks` | Picks that were traded within a draft |
| `sleeper_get_nfl_players` | Full NFL player database with filtering by position, team, or name |
| `sleeper_get_trending_players` | Most-added or most-dropped players over a time window |

## Prerequisites

- **Node.js 18+** — [download](https://nodejs.org) — OR — **Bun** — [download](https://bun.sh)
- A Sleeper account is helpful but not required (the API is fully public)

## Installation

```bash
git clone https://github.com/yooitsgreg/sleeper-mcp.git
cd sleeper-mcp

# pick your package manager:
npm install   # or: pnpm install / yarn / bun install
```

The install triggers a `prepare` hook that compiles TypeScript to `dist/`. No separate build step needed.

## Configuration

Pick the section for your AI client.

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "node",
      "args": ["/absolute/path/to/sleeper-mcp/dist/index.js"]
    }
  }
}
```

### Claude Code (CLI)

Edit `~/.claude/claude.json`:

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "node",
      "args": ["/absolute/path/to/sleeper-mcp/dist/index.js"]
    }
  }
}
```

### VS Code (GitHub Copilot / MCP extension)

Create or edit `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "sleeper": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/sleeper-mcp/dist/index.js"]
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "node",
      "args": ["/absolute/path/to/sleeper-mcp/dist/index.js"]
    }
  }
}
```

After editing the config, restart your AI client.

## Development

```bash
npm run dev     # watch mode (tsx), recompiles on save
npm run build   # compile TypeScript → dist/
npm run clean   # remove dist/
```

### Project structure

```
src/
├── index.ts              # Entry point — wires up McpServer + StdioServerTransport
├── constants.ts          # API base URL, timeouts, character limits
├── types.ts              # TypeScript interfaces for all Sleeper API responses
├── services/
│   └── sleeperClient.ts  # Shared axios client and error handler
└── tools/
    ├── users.ts          # sleeper_get_user
    ├── leagues.ts        # All league tools (9 tools)
    ├── drafts.ts         # All draft tools (5 tools)
    ├── players.ts        # sleeper_get_nfl_players, sleeper_get_trending_players
    └── state.ts          # sleeper_get_nfl_state
```

## Notes

- **No authentication required** — Sleeper's API is free and public.
- **Rate limit** — Sleeper asks that you stay under 1,000 requests/minute.
- **`sleeper_get_nfl_players`** fetches ~5 MB of data. Use the `position_filter`, `team_filter`, or `search` parameters to keep responses manageable. Sleeper recommends caching this data and only refreshing once per day.
- All tools are read-only — this server never writes to Sleeper.

## License

MIT