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/
  • Set the redirect URI to oob (out-of-band / PIN-based)
  • Note your Consumer Key and Consumer Secret

Installation

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:

cp config.json.example config.json

Edit config.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:

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):

{
  "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.