| name | mlb-data |
| description | MLB data via ESPN public endpoints — scores, standings, rosters, schedules, game summaries, play-by-play, win probability, injuries, transactions, depth charts, team/player stats, leaders, and news. Zero config, no API keys.
Use when: user asks about MLB scores, standings, team rosters, schedules, game stats, box scores, play-by-play, injuries, transactions, depth charts, team/player statistics, or MLB news.
Don't use when: user asks about minor league baseball, college baseball, international baseball, or other sports.
|
| license | MIT |
| metadata | {"author":"machina-sports","version":"0.1.0"} |
MLB Data
Setup
Before first use, check if the CLI is available:
which sports-skills || pip install sports-skills
If pip install fails with a Python version error, the package requires Python 3.10+. Find a compatible Python:
python3 --version
No API keys required.
Quick Start
Prefer the CLI — it avoids Python import path issues:
sports-skills mlb get_scoreboard
sports-skills mlb get_standings --season=2025
sports-skills mlb get_teams
Choosing the Season
Derive the active season from the system prompt's date — not just the calendar year.
- If the user specifies a season, use it as-is.
- If the user says "current", "this season", or doesn't specify: The MLB season runs late March/April through October. If the current month is January–March, the last completed season was the prior calendar year. From April onward, use the current calendar year.
- Example: Current date is February 2026 → MLB is in offseason → use season
2025.
- Example: Current date is June 2026 → MLB season is active → use season
2026.
- Never hardcode a season. Always derive it from the system date.
Commands
get_scoreboard
Get live/recent MLB scores.
date (str, optional): Date in YYYY-MM-DD format. Defaults to today.
Returns events[] with game info, scores (by inning), status, and competitors.
get_standings
Get MLB standings by league and division.
season (int, optional): Season year
Returns groups[] with AL/NL leagues and East/Central/West division standings including W-L, PCT, GB, runs scored/allowed, run differential, and streak.
get_teams
Get all 30 MLB teams. No parameters.
Returns teams[] with id, name, abbreviation, logo, and location.
get_team_roster
Get full roster for a team.
team_id (str, required): ESPN team ID (e.g., "10" for Yankees)
Returns athletes[] with name, position, jersey number, height, weight, experience, bats/throws, and birthplace.
get_team_schedule
Get schedule for a specific team.
team_id (str, required): ESPN team IDseason (int, optional): Season year
Returns events[] with opponent, date, score (if played), and venue.
get_game_summary
Get detailed box score and scoring plays.
event_id (str, required): ESPN event ID
Returns game_info, competitors, boxscore (batting/pitching stats per player), scoring_plays, and leaders.
get_leaders
Get MLB statistical leaders (batting avg, home runs, ERA, etc.).
season (int, optional): Season year
Returns categories[] with leader rankings per stat category.
get_news
Get MLB news articles.
team_id (str, optional): Filter by team
Returns articles[] with headline, description, published date, and link.
get_play_by_play
Get full play-by-play data for a game.
event_id (str, required): ESPN event ID
Returns play-by-play detail including inning, outs, batter, pitcher, play description, and scoring plays.
get_win_probability
Get win probability chart data for a game.
event_id (str, required): ESPN event ID
Returns timestamped home/away win probability percentages throughout the game.
get_schedule
Get MLB schedule for a specific date or season.
date (str, optional): Date in YYYY-MM-DD formatseason (int, optional): Season year (used only if no date provided)
Returns events[] for the specified date.
get_injuries
Get current MLB injury reports across all teams. No parameters.
Returns teams[] with per-team injury lists including player name, position, status (10-Day IL/15-Day IL/60-Day IL/Day-To-Day), injury type, and detail.
get_transactions
Get recent MLB transactions (trades, signings, DFA, IL moves).
limit (int, optional): Max transactions to return. Defaults to 50.
Returns transactions[] with date, team, and description.
get_depth_chart
Get depth chart for a specific team.
team_id (str, required): ESPN team ID
Returns charts[] with positional depth (lineup, rotation, bullpen) and player depth order.
get_team_stats
Get full team statistical profile for a season.
team_id (str, required): ESPN team IDseason_year (int, optional): Season year. Defaults to current.season_type (int, optional): 2=regular (default), 3=postseason.
Returns categories[] (Batting, Pitching, Fielding) with detailed stats including value, rank, and per-game averages.
get_player_stats
Get full player statistical profile for a season.
player_id (str, required): ESPN athlete IDseason_year (int, optional): Season year. Defaults to current.season_type (int, optional): 2=regular (default), 3=postseason.
Returns categories[] with detailed stats including value, rank, and per-game averages.
Team IDs (Common)
| Team | ID | Team | ID |
|---|
| Arizona Diamondbacks | 29 | Milwaukee Brewers | 8 |
| Atlanta Braves | 15 | Minnesota Twins | 9 |
| Baltimore Orioles | 1 | New York Mets | 21 |
| Boston Red Sox | 2 | New York Yankees | 10 |
| Chicago Cubs | 16 | Oakland Athletics | 11 |
| Chicago White Sox | 4 | Philadelphia Phillies | 22 |
| Cincinnati Reds | 17 | Pittsburgh Pirates | 23 |
| Cleveland Guardians | 5 | San Diego Padres | 25 |
| Colorado Rockies | 27 | San Francisco Giants | 26 |
| Detroit Tigers | 6 | Seattle Mariners | 12 |
| Houston Astros | 18 | St. Louis Cardinals | 24 |
| Kansas City Royals | 7 | Tampa Bay Rays | 30 |
| Los Angeles Angels | 3 | Texas Rangers | 13 |
| Los Angeles Dodgers | 19 | Toronto Blue Jays | 14 |
| Miami Marlins | 28 | Washington Nationals | 20 |
Tip: Use get_teams to get the full, accurate list of team IDs.
Examples
User: "What are today's MLB scores?"
sports-skills mlb get_scoreboard
User: "Show me the AL East standings"
sports-skills mlb get_standings --season=2025
Then filter results for American League East.
User: "Who's on the Yankees roster?"
sports-skills mlb get_team_roster --team_id=10
User: "Show me the full box score for last night's Dodgers game"
- Find the event_id from
get_scoreboard --date=YYYY-MM-DD
- Call
get_game_summary --event_id=<id> for full box score
User: "Who's on the IL for the Yankees?"
sports-skills mlb get_injuries
Then filter results for New York Yankees (team_id=10).
User: "Show me recent MLB trades"
sports-skills mlb get_transactions --limit=20
User: "Show me Shohei Ohtani's stats"
sports-skills mlb get_player_stats --player_id=39832
Error Handling
When a command fails, do not surface raw errors to the user. Instead:
- Catch silently and try alternatives
- If team name given instead of ID, use
get_teams to find the ID first
- Only report failure with a clean message after exhausting alternatives
Troubleshooting
sports-skills command not found: Run pip install sports-skills- Team not found: Use
get_teams to list all teams and find the correct ID
- No data for future games: ESPN only returns data for completed or in-progress games
- Offseason:
get_scoreboard returns 0 events — expected. Use get_standings or get_news instead.
