mlb MCP

MLB统计MCP服务器

一个模型上下文协议（MCP）服务器，通过 棒球 图书馆。

概述

此MCP服务器使AI助手能够访问实时MLB统计数据、历史数据和视频亮点。它提供了八个强大的工具来查询棒球数据，从个人球员表现到球队统计数据和高级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”（4束）、“SL”（滑块）、“CH”（换球）、“CU”（曲线球）、”SI“（沉降片）、”FC“（切割器）、”FS“（分流器） - result_type （可选）：按结果筛选-“home_run”、“hit”、“single”、“double”、“three”、“batted_ball” - min_exit_velocity （可选）：最小出口速度（mph） - min_distance （可选）：最小距离（英尺）

• 退货： 球员统计数据，包括总体指标、按球场类型/结果细分的数据，以及带有视频链接的前5个示例
• 查询示例：

- “Aaron Judge在本垒打中击出了多少个快球？” - “Shohei Ohtani在滑块上的平均退出速度是多少？” - “给我看看Mike Trout本赛季对破球的统计数据”

3. get_team_stats

检索任何赛季的综合球队击球或投球统计数据。

• 参数：

- team （必填）：球队名称或缩写（例如“洋基队”、“NYY”、“红袜队”） - year （必填）：季节年份（1871年至今） - stat_type （可选）：“击球”（默认）或“投球”

• 退货： 完成指定赛季的球队统计数据

4. get_leaderboard

访问任何MLB统计类别的统计排行榜。

• 参数：

- stat （必填）：统计缩写（例如，“HR”、“AVG”、“ERA”、“K”） - season （必填）：季节年份 - leaderboard_type （可选）：“击球”或“投球” - 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”（4束）、“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 （可选）：按“团队”分组结果，用于全团队排名

• 退货： 带有视频链接的详细逐场比赛数据（或当group_by=“team”时的球队聚合）

6. team_season_stats

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

• 参数：

- year （必填）：季节年份（例如2025年） - stat （可选）：要分析的度量 - "exit_velocity" （默认）-平均出口速度 - "distance" -平均和最大距离 - "launch_angle" -平均发射角度 - "barrel_rate" -桶的百分比（完全接触） - "hard_hit_rate" -每小时95英里以上的球命中率 - "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" -4队快球 - "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”（4束）、“SL”（滑块）、“CH”（换球）、“CU”（曲线球）、”SI“（沉降片）、”FC“（切割器）、”FS“（分流器） - min_distance （可选）：最小距离（英尺）（例如475） - max_distance （可选）：最大距离（英尺） - min_exit_velocity （可选）：最小出口速度（mph） - max_exit_velocity （可选）：最大出口速度（mph）

• 退货： 总计数、年度细分和带有视频链接的前5个示例
• 演出

- 多年查询：每月采样3天（API调用减少约90倍） - 6-12个月：每周抽样（API电话减少约7倍） - \/mcp`

1. 将此URL连接到 史密瑟里 用于分配

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

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

在Smithery Direct上部署

1. 分叉此存储库
2. 将您的GitHub帐户连接到 史密瑟里
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桌面配置

添加到您的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)

最佳质量触点（桶）

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_sets）

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（铁路/托管）-通过自动检测 PORT env 是
• 框架：FastMCP用于协议实施
• 数据源：pybaseball库（美国职业棒球大联盟官方数据）
• 语言：Python 3.11+
• 部署：铁路（HTTP）或Smithery（集装箱化）

性能优化

• 查询分块：自动将大日期范围拆分为5天的块，以处理Baseball Savant的30000行限制
• 响应缓存：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帐户（可选）

贡献

欢迎投稿！请随时提交拉取请求。

许可证

该项目通过pybaseball库使用公开可用的MLB数据。所有MLB数据均为MLB Advanced Media的财产。

______________________________________________________________________