使用说明

棒球mcp

用于大联盟棒球和小联盟棒球数据的MCP（模型上下文协议）服务器。

概述

此MCP服务器通过官方API和网络抓取提供对MLB、小联盟棒球和日本职业棒球（NPB）数据的全面访问。它允许您搜索球员、球队、查看赛程、查看排名，并访问各级职业棒球的比赛数据，包括Triple-A、Double-A、High-A、Single-A、新秀联赛和日本职业棒球。

特性

球员数据

按姓名搜索玩家（所有级别的现役和退役玩家）
按ID检索详细的玩家信息
获取美国职业棒球大联盟和小联盟的全面球员统计数据（职业生涯、赛季、比赛日志）
访问击球、投球和防守统计数据
新增：获取Statcast击球指标 （出口速度、发射角度、枪管速度）-仅限MLB
新增：获取Statcast投球指标 （旋转速率、速度、俯仰运动）-仅限MLB

团队数据

搜索和浏览美国职业棒球大联盟和所有小联盟级别的球队
获取详细的团队信息
查看球队名单（现役，40人，整个赛季）
访问团队统计数据和历史数据

游戏数据

通过日期过滤查看任何联赛级别的比赛日程
获取详细的比赛信息和拳击比分（美国职业棒球大联盟和小联盟）
访问正在进行的游戏的实时游戏提要（仅限美国职业棒球大联盟）
查看游戏状态和分数

支架

查看当前联盟排名（仅限MLB）
访问分区排名
查看通配符排名

小联盟支持

新增：完全支持小联盟数据 包括：
- AAA级
- 双A（AA）
- 高A（A+）
- 单曲A（A）
- 新秀（R）
使用ID获取可用的体育/联赛
访问所有小联盟级别的球员统计数据、球队名单和时间表

NPB（日本棒球）支持

新：日本职业棒球整合 特点：
- 在中央和太平洋联赛中搜索球员
- 所有12个NPB团队的团队信息
- 玩家统计数据（传统和高级指标）
- 支持罗马化的日语姓名搜索
- 智能玩家选择：自动找到具有NPB统计数据的正确玩家
- 多源数据聚合：
  - 棒球参考：所有NPB玩家的历史数据（1936年至今）
  - NPB官员：当前名册和最新统计数据（2008年至今）
- 历史报道：像Sadaharu Oh这样的传奇人物的完整职业生涯统计数据（868 HRs）

著名的NPB玩家：

传说：吴贞治、长岛重雄、野村克也、前本健夫
MLB跨界铃木一郎、大谷正平、松井秀树、于大维、野茂秀
当前明星：村上春树、山田彻、山本义信
完整的职业统计 包括逐年细分

安装

此项目使用 uv 用于Python包管理。要安装：

# Clone the repository
git clone https://github.com/yourusername/baseball-mcp.git
cd baseball-mcp

# Install dependencies with uv
uv sync

# Install the package in editable mode (for development)
uv pip install -e .

全局安装（建议用于Claude Code）

要使棒球mcp服务器在所有Claude Code实例中全局可用，请执行以下操作：

# From the baseball-mcp directory, install globally
uv tool install .

# Add the MCP server to Claude Code at user scope
claude mcp add baseball-mcp -s user -- baseball-mcp

全局安装后 baseball-mcp 命令将在系统范围内可用，Claude Code将能够从任何目录使用它。

用法

运行MCP服务器

如果全局安装：

baseball-mcp

或者直接从源代码运行：

uv run src/baseball_mcp_server.py

可用工具

`get_available_sports`

在美国职棒大联盟统计API中获取所有可用运动/联赛的列表。

参数： 无

例子：

{
  "tool": "get_available_sports",
  "arguments": {}
}

`search_player`

按姓名搜索棒球运动员（所有级别）。

参数：

search_str （字符串，必填）：要搜索的玩家名称
sport_id （整数，可选）：运动ID（MLB/MiLB为1，NPB为31）

例子：

{
  "tool": "search_player",
  "arguments": {
    "search_str": "Jose Altuve"
  }
}

NPB示例：

{
  "tool": "search_player",
  "arguments": {
    "search_str": "Munetaka Murakami",
    "sport_id": 31
  }
}

`get_player`

获取特定MLB球员的详细信息。

参数：

person_id （整数，必填）：唯一玩家标识符
season （字符串，可选）：游戏季节
accent （布尔值，可选）：在名称中包含重音符号（默认值：true）

例子：

{
  "tool": "get_player",
  "arguments": {
    "person_id": 514888,
    "season": "2024"
  }
}

`get_player_stats`

获取特定球员（MLB、小联盟或NPB）的统计数据。

参数：

person_id （整数/字符串，必填）：唯一玩家标识符（int表示MLB/MiLB，字符串表示NPB）
stats （字符串，必填）：统计类型：
- MLB/MiLB：“赛季”、“职业生涯”、“年复一年”、“游戏日志”
- NPB：“击球”、“投球”或“逐年”（按赛季细分）
season （字符串，可选）：游戏季节
sport_id （整数，可选）：运动ID-使用1表示MLB（默认），或：
- 11：AAA级
- 12：双A（AA）
- 13：高A（A+）
- 14：单A（A）
- 16：新秀（右）
- 31：日本职业棒球
group （字符串，可选）：统计组（例如，“击球”、“投球”、“防守”）

例子：

{
  "tool": "get_player_stats",
  "arguments": {
    "person_id": 514888,
    "stats": "season",
    "season": "2024",
    "group": "hitting"
  }
}

`search_teams`

搜索棒球队（MLB、小联盟或NPB）。

参数：

season （字符串，可选）：游戏季节
sport_id （整数，可选）：运动ID-使用1表示MLB（默认），或：
- 11-14、16：小联盟ID
- 31：NPB（返回全部12支队伍）
active_status （字符串，可选）：'Y'表示活动，'N'表示非活动，'B'表示两者都有（默认值：'Y]）
league_id （整数，可选）：联盟ID（AL为103，NL为104）-仅限MLB
division_id （整数，可选）：部门ID

例子：

{
  "tool": "search_teams",
  "arguments": {
    "season": "2024",
    "league_id": 103
  }
}

`get_team`

获取特定MLB球队的详细信息。

参数：

team_id （整数，必填）：唯一团队标识符
season （字符串，可选）：游戏季节

例子：

{
  "tool": "get_team",
  "arguments": {
    "team_id": 117
  }
}

`get_team_roster`

获取特定MLB球队的名单。

参数：

team_id （整数，必填）：唯一团队标识符
roster_type （字符串，可选）：排班类型（默认值：“活动”）
season （字符串，可选）：游戏季节
date （字符串，可选）：特定日期（格式：YYYY-MM-DD）

例子：

{
  "tool": "get_team_roster",
  "arguments": {
    "team_id": 117,
    "roster_type": "40Man"
  }
}

`get_schedule`

获取MLB比赛时间表。

参数：

sport_id （整数，可选）：运动ID（默认值：MLB为1）
season （字符串，可选）：游戏季节
start_date （字符串，可选）：开始日期（格式：YYYY-MM-DD）
end_date （字符串，可选）：结束日期（格式：YYYY-MM-DD）
team_id （整数，可选）：按特定团队筛选
game_type （字符串，可选）：比赛类型（例如，“R”代表常规赛）

例子：

{
  "tool": "get_schedule",
  "arguments": {
    "start_date": "2024-07-01",
    "end_date": "2024-07-07",
    "team_id": 117
  }
}

`get_game_info`

获取特定游戏的详细信息。

参数：

game_pk （整数，必填）：代表游戏的唯一主键

例子：

{
  "tool": "get_game_info",
  "arguments": {
    "game_pk": 717676
  }
}

`get_standings`

获取联赛排名。

参数：

league_id （整数，必填）：联赛ID（AL为103，NL为104）
season （字符串，可选）：游戏季节
standings_type （字符串，可选）：排名类型（默认：“常规赛季”）
date （字符串，可选）：特定日期（格式：YYYY-MM-DD）

例子：

{
  "tool": "get_standings",
  "arguments": {
    "league_id": 103,
    "season": "2024"
  }
}

`get_live_game_feed`

获取正在进行的游戏的实时馈送数据。

参数：

game_pk （整数，必填）：代表游戏的唯一主键

例子：

{
  "tool": "get_live_game_feed",
  "arguments": {
    "game_pk": 717676
  }
}

`get_player_statcast_batting`

获取球员的Statcast击球指标，包括退出速度、发射角度和桶速。

参数：

player_name （字符串，必填）：玩家的全名（例如“Aaron Judge”）
start_date （字符串，可选）：YYYY-MM-DD格式的开始日期
end_date （字符串，可选）：YYYY-MM-DD格式的结束日期
season （字符串，可选）：季节年份（例如“2024”）

例子：

{
  "tool": "get_player_statcast_batting",
  "arguments": {
    "player_name": "Aaron Judge",
    "season": "2024"
  }
}

退货：

平均和最大出口速度
发射角度统计
枪管率和重击率
预期击球率（xBA）和wOBA
节距类型细分

`get_player_statcast_pitching`

获取球员的Statcast投球指标，包括旋转速度、速度和投球移动。

参数：

player_name （字符串，必填）：玩家的全名（例如“Gerrit Cole”）
start_date （字符串，可选）：YYYY-MM-DD格式的开始日期
end_date （字符串，可选）：YYYY-MM-DD格式的结束日期
season （字符串，可选）：季节年份（例如“2024”）

例子：

{
  "tool": "get_player_statcast_pitching",
  "arguments": {
    "player_name": "Gerrit Cole",
    "season": "2024"
  }
}

退货：

按俯仰类型划分的俯仰速度（平均值和最大值）
按音高类型划分的旋转速率
俯仰运动（水平和垂直断裂）
音高使用百分比
Whiff速率

需求

Python 3.12+
uv 包管理器
中列出的依赖关系 pyproject.toml

发展

项目结构：

baseball-mcp/
├── src/
│   ├── baseball_mcp_server.py  # Main MCP server implementation
│   ├── mlb_stats_api.py       # MLB Stats API client functions
│   ├── statcast_api.py        # Statcast/pybaseball client functions
│   ├── data_utils.py          # Utilities for formatting MLB data
│   └── cache_utils.py         # Caching mechanism for API responses
├── test/
│   ├── test_dodgers_stats.py  # Example test script
│   ├── test_statcast.py       # Statcast tools test script
│   ├── test_mlb_stats_api.py  # Unit tests for MLB Stats API
│   └── test_statcast_api.py   # Unit tests for Statcast API
├── pyproject.toml             # Project configuration and dependencies
├── README.md                  # User documentation
└── CLAUDE.md                  # Developer documentation

例子

小联盟示例

获取可用的体育/联赛

{
  "tool": "get_available_sports",
  "arguments": {}
}

获得AAA级团队

{
  "tool": "search_teams",
  "arguments": {
    "sport_id": 11
  }
}

获取小联盟球员统计数据

{
  "tool": "get_player_stats",
  "arguments": {
    "person_id": 702616,
    "stats": "season",
    "sport_id": 11,
    "season": "2024"
  }
}

注意：此示例获取Jackson Holliday的Triple-A统计数据

获得双A时间表

{
  "tool": "get_schedule",
  "arguments": {
    "sport_id": 12,
    "start_date": "2024-06-01",
    "end_date": "2024-06-07"
  }
}

MLB示例

小联盟示例

NPB示例

组建NPB团队

{
  "tool": "search_teams",
  "arguments": {
    "sport_id": 31
  }
}

搜索NPB玩家

{
  "tool": "search_player",
  "arguments": {
    "search_str": "Murakami",
    "sport_id": 31
  }
}

获取NPB玩家统计数据

{
  "tool": "get_player_stats",
  "arguments": {
    "person_id": "npb_munetaka_murakami_2024",
    "stats": "batting",
    "sport_id": 31,
    "season": "2024"
  }
}

获取历史NPB统计数据（传奇）

{
  "tool": "search_player",
  "arguments": {
    "search_str": "Sadaharu Oh",
    "sport_id": 31
  }
}

然后获取他们的职业统计数据：

{
  "tool": "get_player_stats",
  "arguments": {
    "person_id": "br_oh----000sad",
    "stats": "batting",
    "sport_id": 31
  }
}

获取NPB逐年统计数据

关于NPB职业生涯的逐季细分：

{
  "tool": "get_player_stats",
  "arguments": {
    "person_id": "br_cabrer001ale",
    "stats": "yearByYear",
    "sport_id": 31
  }
}

获取MLB球员的NPB统计数据

搜索在两个联赛中都打过球的球员：

{
  "tool": "search_player",
  "arguments": {
    "search_str": "Ichiro Suzuki",
    "sport_id": 31
  }
}

缓存

服务器实现了基于文件的缓存机制来提高性能：

默认情况下，Statcast数据缓存24小时
缓存文件存储在 .cache 目录
对相同数据的后续请求将从缓存中提供服务

api参考

此服务器使用：

MLB统计API （statsapi.mlb.com）获取玩家、团队和游戏数据
棒球野蛮人 （通过pybaseball）获取Statcast指标，包括出口速度、发射角度和旋转速率
NPB官方网站 （npb.jp）日本棒球统计数据（2008年至今）

使用说明

棒球mcp

概述

特性

球员数据

团队数据

游戏数据

支架

小联盟支持

NPB（日本棒球）支持

著名的NPB玩家：

安装

全局安装（建议用于Claude Code）

用法

运行MCP服务器

可用工具

get_available_sports

search_player

get_player

get_player_stats

search_teams

get_team

get_team_roster

get_schedule

get_game_info

get_standings

get_live_game_feed

get_player_statcast_batting

get_player_statcast_pitching

需求

发展

例子

小联盟示例

获取可用的体育/联赛

获得AAA级团队

获取小联盟球员统计数据

获得双A时间表

MLB示例

小联盟示例

NPB示例

组建NPB团队

搜索NPB玩家

获取NPB玩家统计数据

获取历史NPB统计数据（传奇）

获取NPB逐年统计数据

获取MLB球员的NPB统计数据

缓存

api参考

相关 MCP

世界杯数据服务

足球数据API

梦幻足球数据服务

NHL数据API服务

梦幻英超AI助手

足球比赛数据服务

`get_available_sports`

`search_player`

`get_player`

`get_player_stats`

`search_teams`

`get_team`

`get_team_roster`

`get_schedule`

`get_game_info`

`get_standings`

`get_live_game_feed`

`get_player_statcast_batting`

`get_player_statcast_pitching`