MLB API MCP服务器
 
A. 模型上下文协议（MCP） 服务器，通过基于FastMCP的接口提供对MLB统计数据和棒球数据的全面访问。
概述
此MCP服务器充当AI应用程序和MLB数据源之间的桥梁，实现棒球统计数据、比赛信息、球员数据等无缝集成到AI工作流程和应用程序中。
特性
MLB数据访问
- 当前排名 适用于所有按联赛、赛季和日期灵活筛选的MLB球队
- 游戏时间表 以及支持日期范围的结果
- 球员统计 包括传统和剑术统计数据（WAR、wOBA、wRC+）
- 团队信息 以及各种名册类型的名册
- 实时游戏数据 包括箱分、线分和逐局比赛
- 游戏亮点 得分游戏
- 球员和球队搜索 功能
- 信息草案 获奖者
- 游戏节奏统计 以及阵容信息
MCP工具
所有MLB/统计/游戏/玩家/团队等功能都作为MCP工具公开，而不是作为RESTful HTTP端点公开。这些工具可通过以下方式访问 /mcp/ 使用MCP协议的端点。有关可用工具及其说明的列表，请访问 /tools/ 当服务器正在运行时。
关键MCP工具
get_mlb_standings-当前美国职业棒球大联盟排名，包括联赛和赛季过滤器get_mlb_schedule-特定日期、范围或球队的比赛时间表get_mlb_team_info-详细的团队信息get_mlb_player_info-球员履历信息get_mlb_boxscore-完整的游戏方块得分get_mlb_linescore-逐局游戏得分get_mlb_game_highlights-游戏视频集锦get_mlb_game_scoring_plays-使用事件过滤功能逐个播放数据get_mlb_game_pace-游戏持续时间和节奏统计get_mlb_game_lineup-游戏的详细阵容信息get_multiple_mlb_player_stats-传统玩家统计get_mlb_sabermetrics-高级统计（WAR、wOBA等）get_mlb_roster-具有各种名册类型的团队名册get_mlb_search_players-按名字搜索玩家get_mlb_search_teams-按名称搜索团队get_mlb_players-某项运动/赛季的所有球员get_mlb_teams-某项运动/赛季的所有球队get_mlb_draft-按年份分列的信息草案get_mlb_awards-获奖者get_current_date-当前日期get_current_time-当前时间
有关完整列表和详细说明，请参阅 /tools/ 或 /docs 当服务器正在运行时。
HTTP端点
以下HTTP端点可用：
/-重定向到/docs/docs-交互式API文档和工具列表/health/-健康检查端点/mcp/info-MCP服务器信息/tools/-所有可用MCP工具列表/mcp/（POST）-MCP兼容客户端的MCP协议端点
注： MLB/统计/游戏/玩家/团队等没有RESTful HTTP端点。所有这些功能都可以通过MCP工具通过以下方式访问 /mcp/ 终点。MCP集成
- 与启用MCP的AI应用程序兼容
- 基于工具的交互模型，具有全面的端点描述
- 自动生成API文档
- 模式验证和类型安全
- 完整的响应模式描述，以实现更好的AI集成
安装
通过Smithery安装
通过以下方式为Claude Desktop自动安装MLB API服务器 史密瑟里:
npx -y @smithery/cli install @guillochon/mlb-api-mcp --client claude选项1：本地安装
- 如果您还没有安装uv：
curl -LsSf https://astral.sh/uv/install.sh | sh- 克隆存储库：
git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp- 创建并激活虚拟环境：
uv venv
source .venv/bin/activate # On Unix/macOS
# or
.venv\Scripts\activate # On Windows- 安装依赖项：
uv pip install -e .选项2：Docker安装
- 克隆存储库：
git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp- 构建Docker镜像：
docker build -t mlb-api-mcp .- 运行容器（默认时区为UTC，使用Python 3.12）：
docker run -p 8000:8000 mlb-api-mcp设置时区
要在本地时区运行容器，请传递 TZ 环境变量（例如纽约）：
docker run -e TZ=America/New_York -p 8000:8000 mlb-api-mcp替换 America/New_York 根据您的期望 IANA时区名称.
服务器将在以下时间可用 http://localhost:8000 与：
- MCP服务器:
http://localhost:8000/mcp/ - 文档:
http://localhost:8000/docs
Docker选项
您还可以使用其他选项运行容器：
# Run in detached mode
docker run -d -p 8000:8000 --name mlb-api-server mlb-api-mcp
# Run with custom port mapping
docker run -p 3000:8000 mlb-api-mcp
# View logs
docker logs mlb-api-server
# Stop the container
docker stop mlb-api-server
# Remove the container
docker rm mlb-api-server用法
启动服务器
在本地运行MCP服务器：
# For stdio transport (default, for MCP clients like Smithery)
uv run python main.py
# For HTTP transport (for web access)
uv run python main.py --http服务器将以以下方式启动：
- MCP服务器 在…上
http://localhost:8000/mcp/ - 交互式API文档 可在
http://localhost:8000/docs
MCP客户端集成
该服务器可以集成到任何兼容MCP的应用程序中。服务器提供以下工具：
- 检索团队排名和时间表
- 获取全面的球员和球队统计数据
- 访问实时游戏数据和历史记录
- 搜索球员和球队
- 获取战争等军事统计数据
- 还有更多。..
API文档
服务器运行后，请访问 http://localhost:8000/docs API综合文档，包括：
- 可用HTTP端点
- 所有可用MCP工具列表
/tools/ - 工具说明和参数
- 交互式测试界面
- 参数说明和示例
依赖项
- mcp\[cli\]：支持CLI的MCP兼容服务器框架
- 快速 API：HTTP传输的Web框架
- python mlb statsapi：美国职棒大联盟官方统计API包装
- uvicorn\[标准\]：用于运行应用程序的ASGI服务器
- websockets：WebSocket支持（最新版本以避免弃用警告）
- python dotenv：环境变量管理
- httpx：API请求的HTTP客户端
发展
本项目使用：
- Python 3.10+（Docker使用Python 3.12）
- 用于web框架的FastMCP
- uv用于快速Python包管理
- 建筑管理孵化
- MLB统计API用于全面的棒球数据访问
- Ruff用于修饰和格式化
设置预提交挂钩
- 安装预提交：
pip install pre-commit- 初始化预提交钩子：
pre-commit install现在，每当您提交代码时，linting检查都会自动运行。您也可以手动运行它们：
pre-commit run --all-files贡献
欢迎投稿！请随时提交问题或拉取请求。
许可证
这个项目是开源的。请检查许可证文件以了解详细信息。
测试
该项目包括全面的测试覆盖率，包括pytest和覆盖率报告。
运行测试
# Run all tests with coverage (default)
uv run pytest
# Run tests with verbose output
uv run pytest -v
# Run specific test file
uv run pytest tests/test_mlb_api.py
# Run specific test function
uv run pytest tests/test_mlb_api.py::test_get_mlb_standings
# Run tests without coverage
uv run tests/run_coverage.py test
# Generate HTML coverage report
uv run tests/run_coverage.py html
# Clean up coverage files
uv run tests/run_coverage.py clean覆盖
- 当前覆盖范围：86.27%（超过80%阈值）
- 覆盖范围来源:
mlb_api.py和generic_api.py - 报告：终端输出，HTML(
htmlcov/index.html)，以及XML(coverage.xml) - CI集成：覆盖范围检查和徽章更新在每次推送/PR时自动运行
测试结构
测试套件包括：
- 单元测试 适用于所有MCP工具（MLB API和通用API）
- 错误处理测试 针对API故障
- 边缘案例测试 对于边界条件
- 基于模拟的测试 以避免外部API调用
添加新测试
添加新功能时：
- 将相应的测试用例添加到
tests/test_mlb_api.py - 包括成功和错误场景
- 使用mocking来避免外部依赖
- 确保覆盖率保持在80%以上
示例测试结构：
def test_new_function_success(mcp):
"""Test successful execution of new function"""
new_function = get_tool(mcp, 'new_function')
with patch('mlb_api.external_api_call', return_value={'data': 'success'}):
result = new_function(param='value')
assert 'data' in result
def test_new_function_error_handling(mcp):
"""Test error handling in new function"""
new_function = get_tool(mcp, 'new_function')
with patch('mlb_api.external_api_call', side_effect=Exception("API Error")):
result = new_function(param='value')
assert 'error' in result