Back to Details

mlb-data

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MLB Data

MLB 数据获取

Setup

安装配置

Before first use, check if the CLI is available:
bash
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:
bash
python3 --version  # check version
首次使用前，检查CLI是否可用：
bash
which sports-skills || pip install sports-skills
如果
pip install
因Python版本错误失败，说明该包需要Python 3.10+版本。请找到兼容的Python版本：
bash
python3 --version  # 检查版本

If < 3.10, try: python3.12 -m pip install sports-skills

若版本 < 3.10，尝试：python3.12 -m pip install sports-skills

On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

在安装了Homebrew的macOS上：/opt/homebrew/bin/python3.12 -m pip install sports-skills

No API keys required.
无需API密钥。

Quick Start

快速入门

Prefer the CLI — it avoids Python import path issues:
bash
sports-skills mlb get_scoreboard
sports-skills mlb get_standings --season=2025
sports-skills mlb get_teams
推荐使用CLI——可避免Python导入路径问题：
bash
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.
根据系统提示的日期推导当前活跃赛季——而非仅使用日历年。
  • 如果用户指定赛季，直接使用该赛季。
  • 如果用户说“当前”、“本赛季”或未指定：MLB赛季从3月底/4月初持续到10月。如果当前月份是1-3月，最近结束的赛季为上一日历年；从4月开始，使用当前日历年。
  • 示例：当前日期为2026年2月 → MLB处于休赛期 → 使用赛季
    2025
    。
  • 示例：当前日期为2026年6月 → MLB赛季进行中 → 使用赛季
    2026
    。
  • 请勿硬编码赛季，始终根据系统日期推导。

Commands

命令说明

get_scoreboard

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.
获取MLB实时/近期比分。
  • date
    （字符串，可选）：日期格式为YYYY-MM-DD，默认为今日。
返回包含赛事信息、各局比分、状态和对阵双方的
events[]
数组。

get_standings

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.
获取MLB各联盟和分区的排名。
  • season
    （整数，可选）：赛季年份
返回包含美联/国联及东西中分区排名的
groups[]
数组，包括胜场-负场、胜率、胜差、得分/失分、分差和连胜/连败情况。

get_teams

get_teams

Get all 30 MLB teams. No parameters.
Returns 
teams[]
with id, name, abbreviation, logo, and location.
获取全部30支MLB球队信息，无参数。
返回包含球队ID、名称、缩写、队徽和所在地的
teams[]
数组。

get_team_roster

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.
获取指定球队的完整球员名单。
  • team_id
    （字符串，必填）：ESPN球队ID（例如洋基队为"10"）
返回包含球员姓名、位置、球衣号码、身高、体重、球龄、击球/投球习惯和出生地的
athletes[]
数组。

get_team_schedule

get_team_schedule

Get schedule for a specific team.
  • team_id
    (str, required): ESPN team ID
  • season
    (int, optional): Season year
Returns 
events[]
with opponent, date, score (if played), and venue.
获取指定球队的赛程。
  • team_id
    （字符串，必填）：ESPN球队ID
  • season
    （整数，可选）：赛季年份
返回包含对手、日期、比分（若已赛）和场馆的
events[]
数组。

get_game_summary

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
.
获取详细的技术统计和得分战况。
  • event_id
    （字符串，必填）：ESPN赛事ID
返回
game_info
、
competitors
、
boxscore
（每位球员的打击/投球数据）、
scoring_plays
和
leaders
。

get_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.
获取MLB数据领跑者（打击率、本垒打、防御率等）。
  • season
    （整数，可选）：赛季年份
返回包含各数据类别排名的
categories[]
数组。

get_news

get_news

Get MLB news articles.
  • team_id
    (str, optional): Filter by team
Returns 
articles[]
with headline, description, published date, and link.
获取MLB新闻文章。
  • team_id
    （字符串，可选）：按球队筛选
返回包含标题、摘要、发布日期和链接的
articles[]
数组。

get_play_by_play

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.
获取赛事的完整逐场战况数据。
  • event_id
    （字符串，必填）：ESPN赛事ID
返回包含局数、出局数、打者、投手、战况描述和得分战况的逐场详情。

get_win_probability

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.
获取赛事的获胜概率图表数据。
  • event_id
    （字符串，必填）：ESPN赛事ID
返回赛事全程中主/客场获胜概率的时间戳数据。

get_schedule

get_schedule

Get MLB schedule for a specific date or season.
  • date
    (str, optional): Date in YYYY-MM-DD format
  • season
    (int, optional): Season year (used only if no date provided)
Returns 
events[]
for the specified date.
获取指定日期或赛季的MLB赛程。
  • date
    （字符串，可选）：日期格式为YYYY-MM-DD
  • season
    （整数，可选）：赛季年份（仅在未提供日期时使用）
返回指定日期的
events[]
数组。

get_injuries

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.
获取全MLB当前的伤病报告，无参数。
返回包含各球队伤病名单的
teams[]
数组，包括球员姓名、位置、状态（10天伤停/15天伤停/60天伤停/每日观察）、伤病类型和详情。

get_transactions

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.
获取MLB近期交易信息（交易、签约、指定让渡、伤停变动）。
  • limit
    （整数，可选）：返回的最大交易数量，默认为50。
返回包含日期、球队和描述的
transactions[]
数组。

get_depth_chart

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.
获取指定球队的深度阵容图。
  • team_id
    （字符串，必填）：ESPN球队ID
返回包含各位置深度（首发阵容、投手轮值、牛棚）和球员顺位的
charts[]
数组。

get_team_stats

get_team_stats

Get full team statistical profile for a season.
  • team_id
    (str, required): ESPN team ID
  • season_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.
获取球队某一赛季的完整数据概况。
  • team_id
    （字符串，必填）：ESPN球队ID
  • season_year
    （整数，可选）：赛季年份，默认为当前赛季。
  • season_type
    （整数，可选）：2=常规赛（默认），3=季后赛。
返回包含打击、投球、守备详细数据的
categories[]
数组，包括数据值、排名和场均数据。

get_player_stats

get_player_stats

Get full player statistical profile for a season.
  • player_id
    (str, required): ESPN athlete ID
  • season_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.
获取球员某一赛季的完整数据概况。
  • player_id
    （字符串，必填）：ESPN球员ID
  • season_year
    （整数，可选）：赛季年份，默认为当前赛季。
  • season_type
    （整数，可选）：2=常规赛（默认），3=季后赛。
返回包含详细数据的
categories[]
数组，包括数据值、排名和场均数据。

Team IDs (Common)

常用球队ID

TeamIDTeamID
Arizona Diamondbacks29Milwaukee Brewers8
Atlanta Braves15Minnesota Twins9
Baltimore Orioles1New York Mets21
Boston Red Sox2New York Yankees10
Chicago Cubs16Oakland Athletics11
Chicago White Sox4Philadelphia Phillies22
Cincinnati Reds17Pittsburgh Pirates23
Cleveland Guardians5San Diego Padres25
Colorado Rockies27San Francisco Giants26
Detroit Tigers6Seattle Mariners12
Houston Astros18St. Louis Cardinals24
Kansas City Royals7Tampa Bay Rays30
Los Angeles Angels3Texas Rangers13
Los Angeles Dodgers19Toronto Blue Jays14
Miami Marlins28Washington Nationals20
Tip: Use 
get_teams
to get the full, accurate list of team IDs.
球队ID球队ID
亚利桑那响尾蛇29密尔沃基酿酒人8
亚特兰大勇士15明尼苏达双城9
巴尔的摩金莺1纽约大都会21
波士顿红袜2纽约洋基10
芝加哥小熊16奥克兰运动家11
芝加哥白袜4费城费城人22
辛辛那提红人17匹兹堡海盗23
克利夫兰守护者5圣迭戈教士25
科罗拉多落基山27旧金山巨人26
底特律老虎6西雅图水手12
休斯顿太空人18圣路易斯红雀24
堪萨斯城皇家7坦帕湾光芒30
洛杉矶天使3德州游骑兵13
洛杉矶道奇19多伦多蓝鸟14
迈阿密马林鱼28华盛顿国民20
提示： 使用
get_teams
命令获取完整、准确的球队ID列表。

Examples

使用示例

User: "What are today's MLB scores?"
bash
sports-skills mlb get_scoreboard
User: "Show me the AL East standings"
bash
sports-skills mlb get_standings --season=2025
Then filter results for American League East.
User: "Who's on the Yankees roster?"
bash
sports-skills mlb get_team_roster --team_id=10
User: "Show me the full box score for last night's Dodgers game"
  1. Find the event_id from 
    get_scoreboard --date=YYYY-MM-DD
  2. Call 
    get_game_summary --event_id=<id>
    for full box score
User: "Who's on the IL for the Yankees?"
bash
sports-skills mlb get_injuries
Then filter results for New York Yankees (team_id=10).
User: "Show me recent MLB trades"
bash
sports-skills mlb get_transactions --limit=20
User: "Show me Shohei Ohtani's stats"
bash
sports-skills mlb get_player_stats --player_id=39832
用户：“今天的MLB比分是多少？”
bash
sports-skills mlb get_scoreboard
用户：“展示美联东区的排名”
bash
sports-skills mlb get_standings --season=2025
然后筛选出美国联盟东区的结果。
用户：“洋基队的球员名单有哪些？”
bash
sports-skills mlb get_team_roster --team_id=10
用户：“展示昨晚道奇队比赛的完整技术统计”
  1. 使用
    get_scoreboard --date=YYYY-MM-DD
    获取赛事ID
  2. 调用
    get_game_summary --event_id=<id>
    获取完整技术统计
用户：“洋基队有哪些球员伤停？”
bash
sports-skills mlb get_injuries
然后筛选出纽约洋基队（team_id=10）的结果。
用户：“展示近期的MLB交易”
bash
sports-skills mlb get_transactions --limit=20
用户：“展示大谷翔平的数据”
bash
sports-skills mlb get_player_stats --player_id=39832

Error Handling

错误处理

When a command fails, do not surface raw errors to the user. Instead:
  1. Catch silently and try alternatives
  2. If team name given instead of ID, use 
    get_teams
    to find the ID first
  3. Only report failure with a clean message after exhausting alternatives
当命令执行失败时，请勿向用户展示原始错误信息，应按以下步骤处理：
  1. 静默捕获错误并尝试替代方案
  2. 如果用户提供的是球队名称而非ID，先使用
    get_teams
    命令查找对应ID
  3. 仅在尝试所有替代方案后，用简洁的消息告知用户失败情况

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.
  • sports-skills
    命令未找到    ：执行
    pip install sports-skills
  • 球队未找到：使用
    get_teams
    命令列出所有球队并查找正确ID
  • 未来赛事无数据：ESPN仅返回已完成或进行中赛事的数据
  • 休赛期：
    get_scoreboard
    返回0条赛事——此为正常情况，可改用
    get_standings
    或
    get_news
    命令。