内容
# MLB MCP 服务器
一个 MCP（模型上下文协议）服务器，为任何支持 MCP 的大型语言模型（LLM）提供实时访问美国职业棒球大联盟（MLB）和小联盟棒球数据的功能，通过免费的 [MLB 统计数据 API](https://statsapi.mlb.com/)（statsapi.mlb.com）。
**无需 API 密钥。** 无需注册。 无速率限制密钥。 它直接运行。
## 安装
```bash
npm install @jerrysv/mlb-mcp-server
```
或直接使用 npx 运行：
```bash
npx @jerrysv/mlb-mcp-server
```
## 使用
将球队名称作为参数传递以跟踪特定球队。 服务器在启动时将名称模糊匹配到 MLB 统计数据 API。
```bash
# 通用模式 — 所有工具都有效，没有预配置的球队
npx @jerrysv/mlb-mcp-server
# 按名称跟踪特定球队
npx @jerrysv/mlb-mcp-server 水手队 钻石背心队 "希尔斯伯勒霍普斯"
# 按球队 ID 跟踪
npx @jerrysv/mlb-mcp-server 136 109 419
# 按缩写跟踪
npx @jerrysv/mlb-mcp-server SEA ARI
# 混合使用
npx @jerrysv/mlb-mcp-server 水手队 109 "希尔斯伯勒霍普斯"
```
球队名称会进行模糊匹配，因此像 "Diamonbacks" 或 "Seattel Mariners" 这样的拼写错误仍将正确解析。 服务器将模糊匹配记录到标准错误流中，以便您可以验证。
当跟踪球队时，服务器通过 `get_tracked_teams` 和 `resolve_team` 公开它们，以便快速查找。 如果没有球队参数，LLM 仍然可以通过 `get_all_mlb_teams` 发现任何球队。
## 您将获得
### 工具（22）
| 类别 | 工具 |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| **球队** | `get_tracked_teams`、`resolve_team`、`get_team_roster`、`get_all_mlb_teams`、`get_team_affiliates` |
| **球员** | `find_player`、`get_player`、`search_player_on_team` |
| **比赛和赛程** | `get_games_today`、`get_games_by_date`、`get_team_schedule` |
| **实时比赛数据** | `get_game_feed`、`get_box_score`、`get_line_score`、`get_play_by_play` |
| ** standings** | `get_standings` |
| **统计数据和领袖** | `get_player_stats`、`get_team_stats`、`get_team_leaders`、`get_league_leaders` |
| **交易** | `get_transactions` |
| **场馆** | `get_venues` |
| **赛季和参考** | `get_current_season`、`get_sport_ids` |
### 资源（3）
| 资源 | URI | 描述 |
| ---------------------- | -------------------------- | ------------------------------------------------------------- |
| **跟踪球队** | `mlb://tracked-teams` | 球队 ID、缩写、别名、联盟和体育 ID |
| **球队缩写** | `mlb://team-abbreviations` | 跟踪球队缩写和 ID 的快速参考 |
| **体育 ID** | `mlb://sport-ids` | 联盟级别参考：1=MLB，11=AAA，12=AA，13=高A等. |
### 提示（3）
| 提示 | 参数 | 描述 |
| ----------------- | ------------------------------ | -------------------------------------------------------------------- |
| **球队概览** | `team`（必填） | 球队名单、 standings、近期比赛结果和即将到来的赛程 |
| **比赛回顾** | `date`、`team`（两者可选） | 详细的比赛回顾，包括比分、关键比赛和比赛统计亮点 |
| **球员报告** | `player`（必填） | 球员简介、当前赛季统计数据、近期表现和交易记录 |
## 先决条件
- **Node.js 18+** — 使用 `node --version` 检查
就是这样。 无需 API 密钥。
## 连接到 Claude Code
添加到 `~/.claude.json` 或项目 `.mcp.json` 中：
```json
{
"mcpServers": {
"mlb": {
"command": "npx",
"args": [
"@jerrysv/mlb-mcp-server",
"水手队",
"钻石背心队",
"希尔斯伯勒霍普斯"
]
}
}
}
```
或不带跟踪球队：
```json
{
"mcpServers": {
"mlb": {
"command": "npx",
"args": ["@jerrysv/mlb-mcp-server"]
}
}
}
```
## 连接到其他 MCP 客户端
任何支持 MCP 的客户端（Ollama + Open WebUI、LM Studio 等）都可以使用此服务器。 它通过 **stdio** 进行通信：
```bash
npx @jerrysv/mlb-mcp-server 水手队
```
将您的客户端的 MCP 配置指向该命令。
## 常见的球队 ID
| 球队 | ID | 体育 ID |
| -------------------- | --- | ----------- |
| 西雅图水手队 | 136 | 1（MLB） |
| 亚利桑那钻石背心队 | 109 | 1（MLB） |
| 纽约洋基队 | 147 | 1（MLB） |
| 洛杉矶道奇队 | 119 | 1（MLB） |
| 希尔斯伯勒霍普斯 | 419 | 13（高A） |
使用 `get_all_mlb_teams` 或 `get_sport_ids` 来发现任何球队。
## 工具参考
### 球队
- **`get_tracked_teams`** — 列出此服务器跟踪的球队及其 ID、缩写、别名和联赛信息。
- **`resolve_team`** `(team)` — 将模糊的球队名称或缩写解析为其规范信息。 仅适用于跟踪的球队。
- **`get_team_roster`** `(team_id, roster_type?)` — 获取球队的活跃名单。 名单类型：`active`（默认）、`fullSeason`、`fullRoster`、`depthChart`、`coach`。
- **`get_all_mlb_teams`** `(sport_id?)` — 列出某个联赛级别的所有球队。 体育 ID：1=MLB，11=AAA，12=AA，13=高A，14=单A。
- **`get_team_affiliates`** `(team_id)` — 获取 MLB 球队的次级联赛附属球队。 显示完整的农场系统。
### 球员
- **`find_player`** `(name, team?)` — 按姓名搜索任何 MLB/MiLB 球员。 返回人员 ID、职位、球队和基本生物信息。 球员查找的最佳起点。
- **`get_player`** `(person_id, season?)` — 获取球员的完整详细信息和赛季统计数据，人员 ID。
- **`search_player_on_team`** `(team_id, name)` — 在特定球队的名单中按姓名搜索球员。
### 比赛和赛程
- **`get_games_today`** `(sport_id?)` — 获取今天所有预定比赛的比分和状态。
- **`get_games_by_date`** `(date, sport_id?)` — 获取特定日期（YYYY-MM-DD 格式）的所有比赛。
- **`get_team_schedule`** `(team_id, start_date?, end_date?, sport_id?)` — 获取球队的即将到来的或过去的比赛。 默认从开始日期起 14 天。
### 实时比赛数据
- **`get_game_feed`** `(game_pk)` — 完整的实时比赛 feed：比分、比赛、判决、比分线、天气、预计投手。
- **`get_box_score`** `(game_pk)` — 包含两队击球、投球和守场统计数据的比赛统计表。
- **`get_line_score`** `(game_pk)` — 每局比分、击球次数和失误。
- **`get_play_by_play`** `(game_pk)` — 完整的比赛过程，重点突出得分比赛和最后一场比赛总结。
### standings
- **`get_standings`** `(season?)` — 当前 MLB standings 按分区：胜、负、PCT、落后场次、连胜/连败。
### 统计数据和领袖
- **`get_player_stats`** `(person_id, season?)` — 球员的赛季统计数据（击球、投球、守场）。
- **`get_team_stats`** `(team_id, season?, group?)` — 球队的聚合统计数据。 组：`hitting`（默认）或 `pitching`。
- **`get_team_leaders`** `(team_id, season?, category?)` — 球队的统计领袖。 类别：`homeRuns`、`battingAverage`、`earnedRunAverage`、`strikeouts`等。
- **`get_league_leaders`** `(category?, season?, stat_group?, limit?)` — MLB 范围内的统计领袖。 类别：`homeRuns`、`battingAverage`、`earnedRunAverage`、`strikeouts`、`wins`、`saves`.
### 交易
- **`get_transactions`** `(team_id?, start_date?, end_date?)` — 最近的交易：交易、签约、召集、DFA、IL 移动。 默认过去 7 天。
### 场馆
- **`get_venues`** — MLB 体育场和棒球场馆的信息。
### 赛季和参考
- **`get_current_season`** `(season?)` — 赛季元数据：开始/结束日期、全明星赛、季后赛日期。
- **`get_sport_ids`** — 列出所有联赛级别的体育 ID（MLB=1，AAA=11，AA=12，高A=13等）。
## 示例对话
> "今天有水手队的比赛吗？"
> — 调用 `get_games_today`，然后筛选 SEA
> "告诉我关于 Julio Rodriguez 的信息"
> — 调用 `find_player("Julio Rodriguez")` → 人员 ID 677594，然后 `get_player(677594)`
> "给我看水手队的名单"
> — 调用 `resolve_team("Mariners")` → teamId 136，然后 `get_team_roster(136)`
> "钻石背心队这个赛季表现如何？"
> — 调用 `get_standings`，在 NL 西区找到 ARI
> "希尔斯伯勒霍普斯队接下来有哪些比赛？"
> — 调用 `get_team_schedule(419)`，sportId 13
> "给我亚利桑那州的农场系统"
> — 调用 `get_team_affiliates(109)`
> "给我比赛 777245 的比赛统计表"
> — 调用 `get_box_score(777245)`
> "谁在 MLB 中本垒打领先？"
> — 调用 `get_league_leaders(category: "homeRuns")`
> "最近的水手队交易记录？"
> — 调用 `get_transactions(team_id: 136)`
## 从源代码设置
```bash
git clone <repo-url>
cd mlb
npm install
npm test
node src/index.js 水手队 钻石背心队
```
## 项目结构
```
mlb/
src/
index.js — MCP 服务器（工具、资源、提示）
api-client.js — statsapi.mlb.com 的 HTTP 客户端
teams.js — 动态跟踪球队注册表和模糊解析器
helpers.js — 日期格式化、文本助手
test/
api-client.test.js
helpers.test.js
teams.test.js
package.json
README.md
```
## 运行测试
```bash
npm test
```
87 个测试，无外部依赖于 `@modelcontextprotocol/sdk`。 所有 API 客户端测试都模拟 `fetch` — 无实际网络调用。
## 许可证
MIT
