使用说明

MLB MCP服务器

模型上下文协议（MCP）服务器，通过MLB Stats API提供全面的MLB统计和数据。该服务器提供命令行界面和基于web的Streamlit聊天界面，用于与MLB数据交互。

更新日志

v3.0--Anthropic SDK（无需AWS）

将AWS Bedrock+Strands Agent替换为Anthropic SDK。仅使用一个 ANTHROPIC_API_KEY --无需云帐户或IAM设置。

变化：

streamlit_app.py 使用适当的Anthropic工具使用代理循环重写
移除 boto3 和 strands-agents 依赖项
添加 python-dotenv 和 anthropic 依赖关系
新 .env.example 快速设置模板
颠簸版本 0.2.0

v2.0--棒球策略代理

添加了四个由MLB Statcast（通过pybaseball）支持的战略投球呼叫工具，以及一个升级的AI角色，其推理方式类似于投球教练。

新工具：

pitcher_arsenal --Statcast音高混合、速度、旋转速率、吸气速率和每种音高类型的xBA
batter_zone_profile --Statcast数据中的热区/冷区图和节距类型弱点
pitcher_vs_batter -通过美国职棒大联盟统计API进行的职业生涯正面对决历史
live_game_context --实时一局、击球次数、跑动者、得分和当前击球手/投手

改进：

Streamlit代理升级为具有结构化战略工作流程的完整投球教练角色
添加 pybaseball Statcast数据访问的依赖性（使用磁盘缓存以提高速度）
修复了中的错误 lastest_season 工具（名称拼写错误，API调用错误，Python函数名称重复）
Pybaseball集成会优雅地降级——即使Pybaseball不可用，所有原始工具也能工作

v1.0--初始版本

17个MCP工具，涵盖比赛数据、赛程、名单、排名、球员统计和联赛领先者
Strands Agent+AWS Bedrock的流媒体聊天界面（在v3.0中被取代）

🖥️ 用户界面预览

以下是来自 MLB经纪人聊天界面 显示了由MCP服务器和基岩规划师提供支持的真实交互和分析。

1.️⃣ 游戏日程查询

经纪人确定了即将到来的蓝鸟队和道奇队之间的世界大赛第五场比赛，包括场地、状态和可能的投手。

2.️⃣ 球员表现分析

该代理检索Vladimir Guerrero Jr.的2025赛季统计数据，并生成一个比较关键绩效指标的自然语言分析。

3.️⃣ 世界大赛与常规赛比较

该系统将Guerrero Jr.的世界大赛数据与他的常规赛平均值进行了比较，展示了使用MLB数据的情境推理。

这些截图突出了 MLB代理人 将结构化MCP工具输出与情境基岩分析相结合，以产生深入的棒球见解。

特性

核心MLB数据工具

游戏信息：Boxscores、亮点、得分游戏、速度数据
团队数据：名册、排名、领队、日程安排
球员统计：个人球员统计数据（击球、投球、防守）
联盟信息：联赛领先者，按赛区排名
实时数据：当前游戏、下一个游戏、上一个游戏

战略/推销召唤工具（v2.0）

现场游戏环境：实时比赛、计数、跑垒手、得分、当前击球手和投手
投手阿森纳：Statcast沥青混合料，包括使用率、速度、旋转率、气味率和xBA
击球区剖面图：Statcast数据中的热区/冷区图和节距类型可利用性
正面交锋：特定投手和击球手之间的职业史

可用MCP工具（共21个）

通用数据工具

工具	说明
`boxscore`	一场比赛的格式化比分
`game_highlight_data`	游戏精彩视频链接
`game_pace_data`	一个赛季的节奏统计
`scoring_play_data`	为一场比赛得分
`last_game` / `next_game`	球队最近/即将到来的比赛
`latest_season`	当前/最新MLB赛季信息
`league_leader_data`	联盟范围内的统计负责人
`linescore`	格式化和原始JSON linescore
`lookup_player` / `lookup_team`	按名称搜索球员和球队
`player_stat_data`	球员统计数据（击球、投球、防守；赛季或职业生涯）
`roster`	球队名单，包括位置和球衣号码
`game_schedule`	按日期范围、团队或对手分类的游戏
`standings`	带通配符的联赛/赛区排名
`team_leaders`	团队统计负责人
`date`	当前日期/时间

战略工具（v2.0）

工具	说明
`live_game_context`	实时游戏状态：局数、跑步者、得分、当前对决
`pitcher_arsenal`	Statcast螺距混合、速度、旋转速率、吸气速率、每种螺距类型的xBA
`batter_zone_profile`	Statcast的热/冷区图（1-14网格）和间距类型弱点
`pitcher_vs_batter`	特定投手和击球手之间的职业生涯正面交锋统计数据

学分

这个项目是建立在优秀的基础上的美国职业棒球大联盟统计API Python库 托德·罗伯茨 （@toddrob99）。MLB-StatsAPI库为MLB的官方Stats API提供了一个干净的Python接口，并处理数据检索和格式化的所有繁重工作。

使用的MLB StatsAPI功能：

游戏数据检索（盒子分数、亮点、时间表）
球员和球队统计
联赛排名和排行榜
实时游戏信息
历史数据访问

我们感谢Todd Roberts和MLB StatsAPI项目的所有贡献者，让Python开发人员可以轻松访问MLB数据。

快速开始

先决条件

Python 3.11或更高版本
一无烟煤API键（免费版可用）

安装

克隆仓库

git clone <repository-url>
cd mlb_mcp_server-main

安装依赖项

pip install anthropic mcp[cli] mlb-statsapi pybaseball streamlit python-dotenv httpx

或者使用紫外线：

uv sync

运行MCP服务器 （独立，用于测试）
```
python -m mcp run mlb_mcp_server.py
```

Web界面（Streamlit）

对于用户友好的聊天界面：

设置环境变量 --复制 .env.example 到 .env 并填写您的密钥：

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-6
SERVER_CMD=python mlb_mcp_server.py

运行Streamlit应用程序:

streamlit run streamlit_app.py

或者使用紫外线：

uv run streamlit run streamlit_app.py

访问界面 在 http://localhost:8501

无需AWS帐户。 UI直接使用Anthropic SDK。你只需要一个 ANTHROPIC_API_KEY.

使用示例

命令行（通过MCP）

# Get today's MLB standings
echo '{"method": "call_tool", "params": {"name": "standings"}}' | uv run mcp run mlb_mcp_server.py

# Get team roster
echo '{"method": "call_tool", "params": {"name": "roster", "arguments": {"team_id": 119}}}' | uv run mcp run mlb_mcp_server.py

Web界面——一般问题

“显示今天的排名”
“拿到道奇队的名单”
“谁是本赛季的本垒打领袖？”
“给我看看第716663场比赛的比分”

Web界面——棒球策略代理（v2.0）

代理人现在像一个 投球教练+接球手它将多个工具调用链接起来，以提供有根据的、情境化的建议：

投球呼叫（接球手视角）：

“我正在为格里特·科尔接球，我们将面对亚伦·贾奇。亚军，第七局1-2计数。我该怎么称呼？”

代理人将：

呼叫 pitcher_arsenal → 查看科尔的投球组合和每个投球的吸气率
呼叫 batter_zone_profile → 找出裁判最薄弱的区域和投球类型
呼叫 pitcher_vs_batter → 在这场比赛中查看职业历史
提供结构化的答案：主要音调建议、设置顺序、避免什么以及情境调整

击球手侦察：

“本赛季弗雷迪·弗里曼与右手投手相比有什么弱点？”

实时游戏内查找：

“目前的统计数字是多少，现在谁在洋基队的比赛中投球？”

投手库侦察：

“给我看看斯宾塞·斯特里德的投球武器库，哪种投球的嗅觉速度最好”

如何获取玩家ID （战略工具所需）：

First look up the player: "Look up player Gerrit Cole"
→ Returns personId: 543037
Then use that ID: pitcher_arsenal(pitcher_id=543037)

配置

环境变量

ANTHROPIC_API_KEY -您的Anthropic API密钥（Streamlit UI所需）
ANTHROPIC_MODEL -克劳德模型ID（默认值： claude-sonnet-4-6)
SERVER_CMD -启动MCP服务器的命令（默认值： python mlb_mcp_server.py)

团队ID参考

常见的美国职业棒球大联盟球队ID（见 current_mlb_teams.json 完整列表）：

洛杉矶道奇队：119
纽约洋基队：147
费城费城人：143
亚特兰大勇士队：144
波士顿红袜队：111

部署选项

1.地方发展

# Install and run locally
uv sync
uv run streamlit run streamlit_app.py

2.Docker部署

创建 Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install uv
RUN uv sync

EXPOSE 8501

CMD ["uv", "run", "streamlit", "run", "streamlit_app.py", "--server.address", "0.0.0.0"]

构建并运行：

docker build -t mlb-mcp-server .
docker run -p 8501:8501 mlb-mcp-server

3.云部署

AWS EC2/ECS

使用上面的Docker方法
配置用于访问Bedrock的AWS凭据
部署到ECS或在EC2实例上运行

Heroku

添加 Procfile:

web: uv run streamlit run streamlit_app.py --server.port=$PORT --server.address=0.0.0.0

通过Git或Heroku CLI部署

铁路/渲染

连接您的GitHub存储库
在平台仪表板中设置环境变量
从主分支使用自动部署

建筑

MCP服务器(`mlb_mcp_server.py`)

基于FastMCP的服务器提供MLB数据工具
通过连接到MLB Stats API mlb-statsapi 包裹
支持格式化文本和原始JSON响应

流媒体接口(`streamlit_app.py`)

基于网络的聊天界面，由Anthropic SDK提供支持
完整的代理工具使用循环：Claude调用MCP工具并对结果进行推理
具有可扩展详细信息的实时工具调用显示

依赖项

anthropic -Anthropic Python SDK（为Streamlit UI提供支持）
mcp[cli] -模型上下文协议框架
mlb-statsapi -MLB统计API客户端
pybaseball -Statcast和高级分析数据（棒球Savant、FanGraphs、棒球参考）
streamlit -Web界面框架
python-dotenv -环境变量加载
httpx -API请求的HTTP客户端

api参考

关键工具参数

`game_schedule`

{
    "date": "MM/DD/YYYY",           # Specific date
    "start_date": "MM/DD/YYYY",     # Date range start
    "end_date": "MM/DD/YYYY",       # Date range end
    "team_id": 119,                 # Team ID
    "season": "2024"                # Season year
}

`player_stat_data`

{
    "personID": 545361,             # Player ID
    "group": "hitting",             # hitting/pitching/fielding
    "type": "season",               # season/career
    "season": "2024"                # Season year
}

`standings`

{
    "leagueID": "103,104",          # AL=103, NL=104
    "division": "all",              # Division filter
    "season": "2024",               # Season year
    "date": "MM/DD/YYYY"            # Historical date
}

`pitcher_arsenal` （v2.0）

{
    "pitcher_id": 543037,           # MLB player ID (MLBAM) — use lookup_player first
    "season": 2025,                 # Season year (default: current year)
    "days_back": 30                 # Optional: only last N days (faster; shows current form)
}

按音高类型细分的回报： usage_pct, avg_velocity_mph, avg_spin_rate_rpm, whiff_rate_pct, called_strike_rate_pct, xba_against.

`batter_zone_profile` （v2.0）

{
    "batter_id": 665742,            # MLB player ID — use lookup_player first
    "season": 2025,                 # Season year (default: current year)
    "days_back": 30,                # Optional: only last N days
    "pitcher_throws": "R"           # Optional: "L" or "R" to split by pitcher handedness
}

退货 zone_profile （14区热/冷网格，带气味率）， pitch_type_splits （可利用球场与危险球场），以及 batter_tendencies （K%，BB%，重挫%）。

`pitcher_vs_batter` （v2.0）

{
    "pitcher_id": 543037,           # MLB player ID of the pitcher
    "batter_id": 592450             # MLB player ID of the batter
}

从美国职棒大联盟统计API返回职业生涯的正面打击和投球统计数据。

`live_game_context` （v2.0）

{
    "game_pk": 716663,              # Optional: specific game ID
    "team_id": 147                  # Optional: find live game for this team
}

退货 inning, inning_half, count （球/击球/出局）， score, current_matchup （击球手+投手，手数和投球数），以及 runners （哪些基地被占领）。

故障排除

常见问题

MCP服务器无法启动
- 确保已安装Python 3.11+
- 跑 uv sync 安装依赖项
- 检查一下 mlb_mcp_server.py 可执行
流式传输连接错误
- 验证环境变量中的MCP服务器命令
- 检查基岩访问的AWS凭据
- 确保安装了所有依赖项
工具调用失败
- 验证所需参数（团队ID、日期）
- 检查MLB统计API的可用性
- 查看错误日志以了解具体问题
pitcher_arsenal / batter_zone_profile 不返回数据
- 这些工具来自《棒球野蛮人》（Statcast）。数据仅在常规赛期间和之后可用。
- 如果玩家ID错误，则不返回任何数据——使用 lookup_player 首先确认正确的ID。
- 试试小一点的 days_back 值（例如。， days_back=30)用于最近的表单查询；整个赛季的拉力更大。
- 首轮查询速度较慢（从Baseball Savant获取）；由于磁盘缓存，对同一玩家/日期范围的后续调用是即时的。
pitcher_vs_batter 返回空统计信息
- 美国职棒大联盟统计API只记录两名球员出现在同一场比赛中时的正面交锋历史。新玩家或罕见的对决可能会空手而归。
live_game_context 返回“无正在进行的游戏”
- 检查游戏是否真的在线。该工具返回今天的完整日程，以便您可以查看即将到来的游戏。
- 供应a team_id 缩小到特定球队的比赛范围。

调试模式

通过设置启用调试日志记录：

logging.basicConfig(level=logging.DEBUG)

贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

许可证

这个项目是开源的。请检查存储库以了解许可证详细信息。

底层MLB StatsAPI库也是开源的，请参阅他们的仓库获取许可证信息。

支持

对于问题和疑问：

检查上面的故障排除部分
查看 MLB StatsAPI文档
查看MLB Stats API文档
在存储库中打开问题