@bdmarvin/mcp-server-sleeper/README.md

A Model Context Protocol (MCP) server providing access to the Sleeper Fantasy Football API.

# Sleeper Fantasy Football MCP Server (@bdmarvin/mcp-server-sleeper)

A Model Context Protocol (MCP) server providing access to the Sleeper Fantasy Football API. This server is designed to:
- Be installable and runnable via `npx @bdmarvin/mcp-server-sleeper`.
- Integrate seamlessly with an MCP Controller.

## Features

- **Direct API Access**: Directly interfaces with the Sleeper API.
- **User Data**: Retrieve user profiles by username or user ID.
- **League Data**: Access detailed league information, including rosters, users within a league, matchups, and playoff brackets.
- **Draft Data**: Retrieve draft details and all picks within a draft.
- **Player Data**: Fetch comprehensive player information.
- **Transaction Data**: Get transaction history (trades, waivers, free agents) for a league.
- **NFL State**: Obtain current NFL season and week information.

## Prerequisites

- **Node.js 18 or later.**
- **An MCP Controller**: This server is designed to be managed by an MCP Controller.

## Installation & Execution via `npx`

This server is intended to be run as a child process by an MCP Controller using `npx`.

To run it (typically done by the controller):
```bash
npx @bdmarvin/mcp-server-sleeper
```
The server will start and listen for MCP messages on its standard input/output (stdio).

### For Developers (Fork & Manual Build)
If you're contributing or modifying this server:
```bash
git clone https://github.com/Bdmarvin1/mcp-server-sleeper.git
cd mcp-server-sleeper
pnpm install 
pnpm run build
# To run locally (simulating npx, for testing the build):
# node dist/index.js 
```

## Available Tools

### `get_user`
- **Description**: Fetches a user object by username or user ID.
- **Input `arguments`**:
    - `identifier` (string, **required**): The username or user ID.

### `get_user_leagues`
- **Description**: Retrieves all leagues for a given user, sport, and season.
- **Input `arguments`**:
    - `userId` (string, **required**): The numerical ID of the user.
    - `sport` (string, **required**): The sport (e.g., `"nfl"`).
    - `season` (string, **required**): The season (e.g., `"2018"`).

### `get_league`
- **Description**: Retrieves details for a specific league.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.

### `get_league_rosters`
- **Description**: Retrieves all rosters in a league.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.

### `get_league_users`
- **Description**: Retrieves all users in a league.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.

### `get_league_matchups`
- **Description**: Retrieves all matchups in a league for a given week.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.
    - `week` (number, **required**): The week number.

### `get_league_winners_bracket`
- **Description**: Retrieves the winners playoff bracket for a league.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.

### `get_league_losers_bracket`
- **Description**: Retrieves the losers playoff bracket for a league.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.

### `get_league_transactions`
- **Description**: Retrieves all free agent transactions, waivers, and trades for a league in a given week.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.
    - `round` (number, **required**): The week/round to pull from.

### `get_league_traded_picks`
- **Description**: Retrieves all traded picks in a league, including future picks.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.

### `get_nfl_state`
- **Description**: Returns information about the current state for NFL.
- **Input `arguments`**: None.

### `get_all_players`
- **Description**: Fetches all players. **Use sparingly (at most once per day) due to large file size.**
- **Input `arguments`**: None.

### `get_trending_players`
- **Description**: Gets a list of trending players based on add/drop activity.
- **Input `arguments`**:
    - `sport` (string, **required**): The sport (e.g., `"nfl"`).
    - `type` (string, **required**): Either `"add"` or `"drop"`.
    - `lookbackHours` (number, optional): Number of hours to look back (default is 24).
    - `limit` (number, optional): Number of results to return (default is 25).

### `get_user_drafts`
- **Description**: Retrieves all drafts by a user for a given sport and season.
- **Input `arguments`**:
    - `userId` (string, **required**): The numerical ID of the user.
    - `sport` (string, **required**): The sport (e.g., `"nfl"`).
    - `season` (string, **required**): The season (e.g., `"2018"`).

### `get_league_drafts`
- **Description**: Retrieves all drafts for a league.
- **Input `arguments`**:
    - `leagueId` (string, **required**): The ID of the league.

### `get_draft`
- **Description**: Retrieves a specific draft.
- **Input `arguments`**:
    - `draftId` (string, **required**): The ID of the draft.

### `get_draft_picks`
- **Description**: Retrieves all picks in a draft.
- **Input `arguments`**:
    - `draftId` (string, **required**): The ID of the draft.

### `get_draft_traded_picks`
- **Description**: Retrieves all traded picks in a draft.
- **Input `arguments`**:
    - `draftId` (string, **required**): The ID of the draft.

## License

MIT

## Contributing

Contributions to `Bdmarvin1/mcp-server-sleeper` are welcome! Please open an issue or pull request.