# Yahoo Fantasy Baseball MCP

An MCP (Model Context Protocol) server that connects Claude to your Yahoo Fantasy Baseball team. Use it to set your daily lineup, scout free agents, and analyze your roster — all through natural conversation.

## Features

- View your roster, stats, standings, scoreboard, and matchup
- Browse and filter available free agents by position
- Set your daily lineup with a single request
- All via Claude Desktop or any MCP-compatible client

## Prerequisites

- Python 3.10+
- A Yahoo developer app with **Fantasy Sports API** access
  - Create one at [developer.yahoo.com/apps/](https://developer.yahoo.com/apps/)
  - Set the redirect URI to `oob` (out-of-band / PIN-based)
  - Note your **Consumer Key** and **Consumer Secret**

## Installation

```bash
cd yahoo-fantasy-baseball-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## Configuration

Copy the example config and fill in your credentials:

```bash
cp config.json.example config.json
```

Edit `config.json`:

```json
{
  "yahoo_consumer_key": "your_consumer_key",
  "yahoo_consumer_secret": "your_consumer_secret",
  "league_id": "123456",
  "team_id": 3,
  "game_code": "mlb",
  "game_id": 422,
  "season": 2025,
  "token_file": ".yahoo_token.json"
}
```

| Field | Description |
|---|---|
| `yahoo_consumer_key` | From your Yahoo developer app |
| `yahoo_consumer_secret` | From your Yahoo developer app |
| `league_id` | Found in your league URL on Yahoo Fantasy |
| `team_id` | Your integer team ID (auto-discovered by setup) |
| `game_code` | Always `"mlb"` for baseball |
| `game_id` | Yahoo's numeric MLB game ID for the season (auto-discovered) |
| `season` | Current season year |
| `token_file` | Path for storing OAuth token (relative to project dir) |

## Authentication Setup

Run the setup script once to complete OAuth and save your token:

```bash
python setup_auth.py
```

This will:
1. Open a browser window to Yahoo's OAuth page
2. Ask you to log in and authorize the app
3. Prompt you to paste the verification code
4. Save the token to `.yahoo_token.json`
5. Auto-discover and save your `team_id` and `game_id`

After setup, the server auto-refreshes the token — you won't need to re-authenticate.

## Claude Desktop Integration

Add the server to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) or Claude Code Config (`$CLAUDE_CONFIG_DIR/.claude.json` on macOS):

```json
{
  "mcpServers": {
    "yahoo-fantasy-baseball": {
      "command": "/path/to/yahoo-fantasy-baseball-mcp/.venv/bin/python",
      "args": ["/path/to/yahoo-fantasy-baseball-mcp/baseball_mcp.py"]
    }
  }
}
```

```
claude mcp add-json "yahoo-fantasy-baseball" '{"command": "/path/to/yahoo-fantasy-baseball-mcp/.venv/bin/python", "args": ["/path/to/yahoo-fantasy-baseball-mcp/baseball_mcp.py"]}'
```

```
claude-personal mcp add-json "yahoo-fantasy-baseball" '{"command": "/Users/carrington/personal/fantasy-sports/yahoo-fantasy-baseball-mcp/.venv/bin/python", "args": ["/Users/carrington/personal/fantasy-sports/yahoo-fantasy-baseball-mcp/baseball_mcp.py"]}'
```

'{"command": "/Users/carrington/personal/fantasy-sports/yahoo-fantasy-baseball-mcp/.venv/bin/python", "args": ["/Users/carrington/personal/fantasy-sports/yahoo-fantasy-baseball-mcp/baseball_mcp.py"]}'

'{"type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "MYPAT" }}'

Restart Claude Desktop and you should see the baseball tools available.

## Available Tools

| Tool | Description |
|---|---|
| `baseball_get_team_info` | Team name, record, standings |
| `baseball_get_roster` | Roster for a date with current position slots |
| `baseball_get_roster_stats` | Season stats for all rostered players |
| `baseball_get_free_agents` | Available free agents filtered by position/sort |
| `baseball_get_player_stats` | Stats + ownership for one player |
| `baseball_get_standings` | League standings |
| `baseball_get_scoreboard` | Scoring period scoreboard |
| `baseball_get_matchup` | Your team's matchup detail |
| `baseball_get_league_settings` | Scoring categories, roster positions, rules |
| `baseball_set_lineup` | Set your daily lineup via Yahoo API |

## Example Prompts

- "Show me my current roster for today"
- "Who are the top available starting pitchers?"
- "Find a better second baseman who is available — compare them to who I have"
- "Set my lineup for today — put [player] on the bench and activate [player]"
- "How does my team compare to my opponent this week?"
- "What are the league standings?"

## Setting Your Lineup

The `baseball_set_lineup` tool requires the **complete roster** — every player must be assigned a slot. The recommended workflow:

1. "Show me my roster for today" → Claude calls `baseball_get_roster`
2. "Move [player] to the bench and start [player] at SP" → Claude calls `baseball_set_lineup` with the full updated list

Valid starting positions: `C`, `1B`, `2B`, `3B`, `SS`, `OF`, `Util`, `SP`, `RP`, `P`

Bench/IL slots: `BN`, `IL`, `IL+`, `NA` (availability depends on your league settings)

## Troubleshooting

**Token expired:** The server auto-refreshes tokens. If you see auth errors, re-run `python setup_auth.py`.

**Wrong team_id:** Check your team URL on Yahoo Fantasy — the number at the end is your team ID.

**game_id is wrong:** Run `python setup_auth.py` again — it will auto-discover the current season's game ID.