使用说明

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倍）
- <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)))"
  }
}

🏟️ 智能团队识别

服务器智能地处理团队名称：

全名：“金莺”→ “BAL”、“红袜队”→ "BOS"
城市：“波士顿”→ “BOS”、“纽约洋基队”→ "NYY"
历史团队：“Expos”→ “MON”、“印第安人”→ "CLE"
目前所有30支MLB球队都有共同的变体支持

📊 团队排名

新的团队聚合功能 statcast_leaderboard:

按团队分组结果，查看整个团队的绩效
计算每个指标的平均值、最大值和计数
非常适合回答“哪支球队击出了最难的本垒打？”
返回全面的团队统计数据，包括桶数和预期指标

安装

在铁路上部署（建议在史密斯里部署）

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

创建一个新的Railway项目并连接您的GitHub存储库
铁路将自动检测 Procfile 并自动部署
您的MCP端点将在 https://<your-railway-domain>/mcp
将此URL连接到史密瑟里用于分配

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

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

在Smithery Direct上部署

分叉此存储库
将您的GitHub帐户连接到史密瑟里
直接从存储库部署

本地开发

# 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的财产。

建于棒球和 FastMCP