# Sleeper MCP

A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for
the public [Sleeper API](https://docs.sleeper.com/). It exposes users, leagues,
rosters, matchups, transactions, drafts, players, trending activity, playoff
brackets, traded picks, and sport state through async FastMCP tools.

Sleeper requires no API key. Please respect its documented guidance to stay
below 1,000 requests per minute. The full players response is several megabytes
and should generally be fetched no more than once per day.

## Install

Requires Python 3.11 or newer and [uv](https://docs.astral.sh/uv/).

```bash
uv sync
```

## Run

The server uses MCP's stdio transport by default:

```bash
uv run sleeper-mcp
```

The equivalent module command is:

```bash
uv run python -m sleeper_mcp.server
```

## Docker

The image is based on `alpine:latest` and runs the MCP server over stdio. Keep
`-i` so the client can talk to the process on stdin.

```bash
docker build -t sleeper-mcp .
docker run --rm -i sleeper-mcp
```

### Cursor (Docker)

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "sleeper-mcp"
      ]
    }
  }
}
```

### Claude Desktop (Docker)

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "sleeper-mcp"
      ]
    }
  }
}
```

## Configure an MCP client

Use the workspace's absolute path in your client configuration (or the Docker
commands above).

### Cursor

Add this server to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/talweiss/Desktop/codeProjects/sleeper-mcp",
        "run",
        "sleeper-mcp"
      ]
    }
  }
}
```

### Claude Desktop

Add the same entry under `mcpServers` in Claude Desktop's configuration:

```json
{
  "mcpServers": {
    "sleeper": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/talweiss/Desktop/codeProjects/sleeper-mcp",
        "run",
        "sleeper-mcp"
      ]
    }
  }
}
```

Restart the client after changing its configuration.

## Development

```bash
uv run pytest
```

The package follows a layered design:

- `client.py` owns HTTP concerns and the Sleeper base URL.
- `service.py` maps methods to documented API endpoints.
- `tools.py` documents and exposes service methods as MCP tools.
- `server.py` wires the layers together and starts FastMCP.