Pybaseball MCP Server

MLB Stats MCP Server

一个 Model Context Protocol (MCP) 服务，通过 pybaseball 库提供全面的 MLB 棒球统计数据和视频集锦。

概述

此 MCP 服务可让 AI 助手访问 MLB 实时统计数据、历史数据和视频集锦。它提供了 8 个强大的工具，用于查询棒球数据，涵盖从个别球员表现到球队统计数据和高级 Statcast 指标。

功能

🎯 8 个核心工具

1. get_player_stats

获取任意 MLB 球员的详细 Statcast 数据，并可按日期筛选。

• 参数：
  • name（必填）：球员姓名（例如，“Mike Trout”、“Ronald Acuña Jr.”）
  • start_date（可选）：开始日期，格式为 YYYY-MM-DD
  • end_date（可选）：结束日期，格式为 YYYY-MM-DD
• **返回：**球员统计数据，包括安打、全垒打、击球初速、发射角和强劲击球率

2. player_statcast

获取特定球员全面的 Statcast 数据，并可按球种和结果进行高级筛选。

• 参数：
  • player_name（必填）：球员姓名（例如，“Aaron Judge”、“Mike Trout”）
  • start_date（可选）：开始日期，格式为 YYYY-MM-DD（默认为当前赛季）
  • end_date（可选）：结束日期，格式为 YYYY-MM-DD（默认为当前赛季）
  • pitch_type（可选）：按球种筛选——'FF'（四缝线速球）、'SL'（滑球）、'CH'（变速球）、'CU'（曲球）、'SI'（伸卡球）、'FC'（卡特球）、'FS'（指叉球）
  • result_type（可选）：按结果筛选——'home_run'、'hit'、'single'、'double'、'triple'、'batted_ball'
  • min_exit_velocity（可选）：最低击球初速，单位为 mph
  • min_distance（可选）：最短击球距离，单位为英尺
• **返回：**球员统计数据，包括总体指标、按球种和结果分类的数据，以及附有视频链接的 5 个示例
• 查询示例：
  • “Aaron Judge 击出过多少支全垒打，且面对的球是速球？”
  • “Shohei Ohtani 面对滑球时的平均击球初速是多少？”
  • “显示 Mike Trout 本赛季面对变化球时的统计数据”

3. get_team_stats

获取任意赛季球队全面的打击或投球统计数据。

• 参数：
  • team（必填）：球队名称或缩写（例如，“Yankees”、“NYY”、“Red Sox”）
  • year（必填）：赛季年份（1871 年至今）
  • stat_type（可选）："batting"（默认）或 "pitching"
• **返回：**指定赛季的完整球队统计数据

4. get_leaderboard

查看 MLB 任意统计类别的排行榜。

• 参数：
  • stat（必填）：统计缩写（例如，“HR”、“AVG”、“ERA”、“K”）
  • season（必填）：赛季年份
  • leaderboard_type（可选）："batting" 或 "pitching"
  • limit（可选）：结果数量（默认：10）
• **返回：**指定统计项目排名靠前的球员

5. statcast_leaderboard

查询高级 Statcast 数据，支持筛选、排序和视频集锦链接。

• 参数：
  • start_date（必填）：开始日期，格式为 YYYY-MM-DD
  • end_date（必填）：结束日期，格式为 YYYY-MM-DD
  • result（可选）：按结果筛选（例如，“home_run”“single”“double”）
  • min_ev（可选）：按最低出球速度筛选
  • min_pitch_velo（可选）：按最低投球速度筛选
  • pitch_type（可选）：按投球类型筛选——'FF'（四缝线速球）、'SL'（滑球）、'CH'（变速球）、'CU'（曲球）、'SI'（伸卡球）、'FC'（卡特球）、'FS'（指叉球）
  • player_name（可选）：按击球手姓名筛选（例如，“Aaron Judge”“Mike Trout”）
  • sort_by（可选）：排序指标：
    • "exit_velocity"（默认）- 出球速度最快的击球
    • "distance" - 飞行距离最远的击球
    • "launch_angle" - 最理想的发射角度
    • "pitch_velocity" - 速度最快的投球
    • "spin_rate" - 旋转率最高的投球
    • "xba" - 预期打击率最高
    • "xwoba" - 预期加权上垒率最高
    • "barrel" - 强劲击球率（完美击球）
  • limit（可选）：结果数量（默认：10）
  • order（可选）：排序顺序——"desc"（默认）或 "asc"
  • group_by（可选）：按 "team" 对结果分组，生成球队排名
• **返回：**详细的逐场数据及视频链接（当 group_by="team" 时返回球队汇总数据）

6. team_season_stats

快速获取球队的 Statcast 指标赛季平均值。针对“哪支球队击球最有力？”等查询进行了优化。

• 参数：
  • year（必填）：赛季年份（例如，2025）
  • stat（可选）：要分析的指标
    • "exit_velocity"（默认）- 平均出球速度
    • "distance" - 平均和最大飞行距离
    • "launch_angle" - 平均发射角度
    • "barrel_rate" - 强劲击球占比（完美击球）
    • "hard_hit_rate" - 出球速度达到 95+ mph 的击球占比
    • "sweet_spot_rate" - 发射角度处于理想范围（8-32°）的击球占比
  • min_result_type（可选）：按结果类型筛选
    • "batted_ball" - 所有进入比赛状态的击球
    • "home_run" - 仅本垒打
    • "hit" - 所有安打（一垒安打、二垒安打、三垒安打和本垒打）
• **返回：**球队排名及平均值、计数和其他统计数据
• **性能：**使用抽样策略（每 7 天抽取一天）和 24 小时缓存，实现即时响应

7. team_pitching_stats

快速获取球队投球方面的 Statcast 指标平均值。针对“哪支球队的投手阵容最好？”等查询进行了优化。

• 参数：
  • year（必填）：赛季年份（例如，2025）
  • stat（可选）：要分析的指标
    • "velocity"（默认）- 平均和最高投球速度
    • "spin_rate" - 平均和最高旋转率
    • "movement" - 投球位移（水平、垂直、总计）
    • "whiff_rate" - 挥空率
    • "chase_rate" - 对好球带外投球的挥棒率
    • "zone_rate" - 位于好球带内的投球占比
    • "ground_ball_rate" - 滚地球占进入比赛状态的击球的比例
    • "xera" - 基于击球质量计算的预期 ERA
  • pitch_type（可选）：按特定投球类型筛选
    • "FF" - 四缝线速球
    • "SL" - 滑球
    • "CH" - 变速球
    • "CU" - 曲球
    • "SI" - 伸卡球
    • "FC" - 卡特球
    • "FS" - 指叉球
• **返回：**球队投球排名及平均值、计数和其他统计数据
• **性能：**使用抽样策略（每 7 天抽取一天）和 24 小时缓存，实现即时响应

8. statcast_count

统计符合特定条件的 Statcast 事件。针对跨年度查询进行了优化，例如“自 2023 年以来，飞行距离至少 475 英尺的本垒打有多少次？”

• 参数：
  • start_date（必需）：开始日期，格式为 YYYY-MM-DD
  • end_date（必需）：结束日期，格式为 YYYY-MM-DD
  • result_type（可选）：要统计的类型——'home_run'（默认）、'hit'、'batted_ball'，或具体类型，如 double
  • player_name（可选）：按击球手姓名筛选（例如，“Aaron Judge”、“Mike Trout”）
  • pitch_type（可选）：按投球类型筛选——'FF'（四缝线速球）、'SL'（滑球）、'CH'（变速球）、'CU'（曲球）、'SI'（伸卡球）、'FC'（卡特球）、'FS'（指叉球）
  • min_distance（可选）：最小飞行距离，单位为英尺（例如 475）
  • max_distance（可选）：最大飞行距离，单位为英尺
  • min_exit_velocity（可选）：最低出球速度，单位为英里/小时
  • max_exit_velocity（可选）：最高出球速度，单位为英里/小时
• 返回： 总次数、按年份细分的数据，以及 5 个代表性示例（附视频链接）
• 性能：
  • 跨年度查询：每月抽样 3 天（API 调用次数约减少 90 倍）
  • 6–12 个月：每周抽样（API 调用次数约减少 7 倍）
  • 少于 6 个月：使用分块处理完整数据
  • 所有查询均缓存 24 小时

🎥 视频集锦集成

statcast_leaderboard 的每条结果都包含详细指标和视频入口：

{
  "rank": 1,
  "player": "Ronald Acuña Jr.",
  "date": "2024-07-20",
  "exit_velocity": 113.7,
  "launch_angle": 23.0,
  "distance": 456.0,
  "result": "home_run",
  "pitch_velocity": 95.2,
  "pitch_type": "FF",
  "spin_rate": 2450,
  "xba": 0.920,
  "xwoba": 1.823,
  "barrel": true,
  "description": "Ronald Acuña Jr. homers (13) on a fly ball to center field.",
  "video_links": {
    "game_highlights_url": "https://www.mlb.com/gameday/745890/video",
    "film_room_search": "https://www.mlb.com/video/search?q=Ronald+Acuna+Jr.+2024-07-20",
    "game_pk": "745890",
    "api_highlights_endpoint": "https://statsapi.mlb.com/api/v1/schedule?gamePk=745890&hydrate=game(content(highlights(highlights)))"
  }
}

🏟️ 智能球队识别

该服务能够智能处理球队名称：

• 全名：“Orioles” → “BAL”，“Red Sox” → “BOS”
• 城市名：“Boston” → “BOS”，“New York Yankees” → “NYY”
• 历史球队：“Expos” → “MON”，“Indians” → “CLE”
• 支持当前 MLB 的全部 30 支球队及其常见别名

📊 球队整体排名

为 statcast_leaderboard 新增球队聚合功能：

• 按球队分组查看球队整体表现
• 计算各项指标的平均值、最大值和次数
• 非常适合回答“哪支球队击出的本垒打最有力？”等问题
• 返回全面的球队统计数据，包括强击球（barrel）次数和预期指标

安装

部署到 Railway（推荐用于 Smithery）

部署到 Railway，以提供 Smithery 可连接的托管 HTTP MCP 端点：

1. 创建新的 Railway 项目并连接 GitHub 仓库
2. Railway 会自动检测 Procfile 并部署
3. MCP 端点将位于 https://<your-railway-domain>/mcp
4. 将此 URL 连接到 Smithery，以便分发

手动启动命令（如有需要）： 如果 Railway 未自动检测到 Procfile，请在 Railway 设置中配置此启动命令：

uv run fastmcp run src/mlb_mcp/server.py:mcp --transport http --host 0.0.0.0 --port $PORT

直接部署到 Smithery

1. Fork 此仓库
2. 将你的 GitHub 账户连接到 Smithery
3. 直接从仓库部署

本地开发

# Clone the repository
git clone https://github.com/yourusername/mlb_mcp.git
cd mlb_mcp

# Install dependencies with uv
uv sync

# Run the server (stdio mode for local testing)
uv run python -m mlb_mcp.server

# Or run with HTTP transport for local HTTP testing
MCP_TRANSPORT=http MCP_PORT=8000 uv run python -m mlb_mcp.server

Claude Desktop 配置

添加到 Claude Desktop 配置中（使用 stdio 传输）：

{
  "mcpServers": {
    "mlb-stats": {
      "command": "uv",
      "args": ["run", "python", "-m", "mlb_mcp.server"],
      "cwd": "/path/to/mlb_mcp"
    }
  }
}

使用示例

球员专属查询（新增！）

Aaron Judge 击出过多少支速球本垒打？

Query: "How many fastballs has Aaron Judge hit for a home run this season?"
Tool: player_statcast("Aaron Judge", "2024-04-01", "2024-10-31", "FF", "home_run")
OR
Tool: statcast_count("2024-04-01", "2024-10-31", "home_run", player_name="Aaron Judge", pitch_type="FF")

球员面对特定投球类型时的表现如何？

Query: "Show me Shohei Ohtani's stats against sliders this season"
Tool: player_statcast("Shohei Ohtani", "2024-04-01", "2024-10-31", "SL")

球员面对特定投球类型时击出的最强劲球

Query: "Show Aaron Judge's hardest hit balls on fastballs"
Tool: statcast_leaderboard("2024-04-01", "2024-10-31", player_name="Aaron Judge", pitch_type="FF", sort_by="exit_velocity", limit=10)

查找飞行距离最长的本垒打

Query: "Show me the longest home runs from yesterday"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", "home_run", None, None, "distance", 10)

面对快速球时击出的最强劲球

Query: "What were the hardest hit balls on 99+ mph pitches last week?"
Tool: statcast_leaderboard("2024-07-14", "2024-07-20", None, 0, 99.0, "exit_velocity", 10)

投出的最快球

Query: "Show me the fastest pitches thrown yesterday"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "pitch_velocity", 10)

旋转速率最高的球

Query: "What pitches had the highest spin rate today?"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "spin_rate", 10)

最优质的击球（Barrel）

Query: "Show me the best quality contact this week"
Tool: statcast_leaderboard("2024-07-14", "2024-07-20", None, None, None, "barrel", 10)

球员赛季数据

Query: "Get Mike Trout's stats for this season"
Tool: get_player_stats("Mike Trout", "2024-04-01", "2024-10-01")

球队表现

Query: "How are the Red Sox doing this year?"
Tool: get_team_stats("Red Sox", 2024, "batting")

联盟领先者

Query: "Who's leading the league in home runs?"
Tool: get_leaderboard("HR", 2024, "batting", 10)

球队整体排名（statcast_leaderboard）

Query: "Which team has the hardest hit home runs this season?"
Tool: statcast_leaderboard("2024-04-01", "2024-10-01", "home_run", None, None, "exit_velocity", 10, "desc", "team")

Query: "Show me teams with the longest average home run distance this month"
Tool: statcast_leaderboard("2024-07-01", "2024-07-31", "home_run", None, None, "distance", 10, "desc", "team")

Query: "Which teams have the highest average pitch velocity?"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "pitch_velocity", 10, "desc", "team")

球队赛季平均数据（team_season_stats）

Query: "What team averages the hardest hit balls in 2025?"
Tool: team_season_stats(2025, "exit_velocity")

Query: "Which team has the highest barrel rate this season?"
Tool: team_season_stats(2025, "barrel_rate")

Query: "Show me teams with the highest hard-hit rate on home runs only"
Tool: team_season_stats(2025, "hard_hit_rate", "home_run")

Query: "What team hits the ball the farthest on average?"
Tool: team_season_stats(2025, "distance")

球队投球分析（team_pitching_stats）

Query: "Which team throws the hardest in 2025?"
Tool: team_pitching_stats(2025, "velocity")

Query: "What team has the best slider spin rate?"
Tool: team_pitching_stats(2025, "spin_rate", "SL")

Query: "Which pitching staff gets the most swings and misses?"
Tool: team_pitching_stats(2025, "whiff_rate")

Query: "Show me teams with the highest ground ball rate"
Tool: team_pitching_stats(2025, "ground_ball_rate")

Query: "Which team has the lowest expected ERA based on contact quality?"
Tool: team_pitching_stats(2025, "xera")

计数查询（statcast_count）

Query: "How many home runs hit over 475 ft have been hit since 2023?"
Tool: statcast_count("2023-01-01", "2025-12-31", "home_run", 475)

Query: "Count all 110+ mph batted balls this season"
Tool: statcast_count("2025-04-01", "2025-10-31", "batted_ball", None, 110)

Query: "How many home runs between 400-450 feet were hit last year?"
Tool: statcast_count("2024-04-01", "2024-10-31", "home_run", 400, None, 450)

Query: "Total hits with exit velocity over 100 mph since 2022"
Tool: statcast_count("2022-01-01", "2025-12-31", "hit", None, 100)

技术详情

架构

• 传输方式：stdio（本地）或 HTTP（Railway/托管）——通过 PORT 环境变量自动检测
• 框架：使用 FastMCP 实现协议
• 数据源：pybaseball 库（MLB 官方数据）
• 语言：Python 3.11+
• 部署：Railway（HTTP）或 Smithery（容器化）

性能优化

• 查询分块：自动将较大的日期范围拆分为 5 天的区块，以应对 Baseball Savant 的 30,000 行限制
• 响应缓存：重复查询缓存 15 分钟，球队赛季统计数据缓存 24 小时
• 向量化操作：使用 NumPy 高效识别球队，而非较慢的 pandas apply() 操作
• 抽样策略：
  • team_season_stats 和 team_pitching_stats：每 7 天抽样一次
  • statcast_count：自适应抽样（跨多年时每月 3 天，6–12 个月时每周抽样）
• 专用工具：针对使用完整数据时会超时的常见聚合查询提供专用工具：
  • team_season_stats：用于击球指标
  • team_pitching_stats：用于投球指标
  • statcast_count：用于跨多年的计数查询
• 延迟加载：仅在需要时加载 pandas、numpy、pybaseball 等重型依赖项，以加快启动速度
• 高效筛选：依次应用筛选条件，尽量减少数据处理开销

主要功能

• 错误处理：针对常见问题提供全面的错误信息
• 类型安全：正确转换类型，以支持 JSON 序列化
• 视频集成：为所有比赛和球队的最佳表现自动添加精彩视频链接
• 智能球队查找：支持全名、缩写、城市名和历史球队

文件结构

mlb_mcp/
├── src/
│   └── mlb_mcp/
│       ├── __init__.py    # Package exports
│       └── server.py      # Main MCP server implementation
├── pyproject.toml         # Project configuration and dependencies
├── smithery.yaml          # Smithery deployment configuration
├── Procfile               # Railway start command
└── README.md              # This file

要求

• Python 3.11 或更高版本
• 用于访问 MLB 数据的互联网连接
• 用于部署的 Smithery 账号（可选）

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

本项目通过 pybaseball 库使用公开的 MLB 数据。所有 MLB 数据均归 MLB Advanced Media 所有。

---

使用 pybaseball 和 FastMCP 构建