# sleeper-mcp

MCP server exposing the read-only [Sleeper](https://sleeper.app) NFL fantasy football API. The server uses stdio transport and supports Node.js 24 or newer.

## Setup

```bash
npm ci
npm run build
```

Run the Vitest suite with:

```bash
npm test
```

Run the build, Oxlint, Oxfmt, and Vitest checks with:

```bash
npm run check
```

Apply automatic formatting with `npm run format`. The compiled MCP entrypoint is `build/index.js`.

## Tools

| Tool                   | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| `get_user`             | Look up one user by exactly one of `username` or `user_id`               |
| `get_leagues`          | Get a user's NFL leagues for an explicit four-digit `season`             |
| `get_league`           | Get details for one `league_id`                                          |
| `get_rosters`          | Get league rosters and annotate player IDs when player data is available |
| `get_users_in_league`  | Get public user and team metadata in a league                            |
| `get_matchups`         | Get weekly matchups and annotate player IDs when available               |
| `get_transactions`     | Get trades, waivers, and free-agent transactions by round                |
| `get_traded_picks`     | Get traded picks, including future picks                                 |
| `get_nfl_state`        | Get the current NFL season, week, and season type                        |
| `get_drafts`           | Get league drafts, newest first according to Sleeper                     |
| `get_draft_picks`      | Get draft picks and any metadata supplied by Sleeper                     |
| `get_trending_players` | Get recent add/drop trends with player names when available              |
| `resolve_players`      | Resolve up to 100 player or defense IDs into player metadata             |

Successful tools return both text content and structured content. Invalid arguments, rate limits, timeouts, network failures, unexpected primary API response shapes, and oversized primary responses are returned as MCP tool errors. Optional player-name enrichment can degrade to a warning when the primary tool result is still available.

## Use with MCP hosts

For local development, replace the path with this checkout's absolute path to `build/index.js`:

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "node",
      "args": ["C:\\path\\to\\sleeper-mcp\\build\\index.js"]
    }
  }
}
```

For the published package, pin the desired version:

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "npx",
      "args": ["-y", "@luccabessa/sleeper-mcp@VERSION"]
    }
  }
}
```

The server waits for MCP protocol traffic on stdin/stdout. Diagnostics are written only to stderr so stdout remains protocol-safe.

## Player cache

- Roster, matchup, and trending enrichment lazily loads the full NFL player database on first use.
- Successful player data is cached in memory for 24 hours.
- Concurrent cache misses share one request.
- A failed refresh retains the last successful data and emits an explicit warning.
- `resolve_players` accepts `force_refresh`, but repeated forced refreshes are limited to once every five minutes.
- `resolve_players` deduplicates IDs and accepts at most 100 IDs per call.

## Sleeper API usage

- This server exposes only the NFL endpoints currently implemented by Sleeper's public read-only API.
- No authentication is required.
- Stay under Sleeper's general limit of 1,000 requests per minute.
- The Sleeper API is free for non-commercial use; commercial use requires separate licensing.
- Attribute Sleeper when redistributing or displaying trending-player data.
- Refer to the [official Sleeper API documentation](https://docs.sleeper.com/) for upstream endpoint behavior.