MLB Stats MCP Server

MLB Stats MCP 服务

这是一个 Python 项目，用于创建 Model Context Protocol（MCP）服务，通过 MLB Stats API 和 pybaseball 库访问 MLB 统计数据，包括 Statcast、FanGraphs 和 Baseball Reference 的统计数据。此服务提供结构化的 API 访问方式，可供兼容 MCP 的客户端使用。

项目结构

• mlb_stats_mcp/ - 主程序包目录
  • server.py - MCP 服务核心实现
  • tools/ - MCP 工具实现
    • mlb_statsapi_tools.py - MLB StatsAPI 工具定义
    • statcast_tools.py - Statcast 数据工具定义
    • pybaseball_plotting_tools.py - 额外的 pybaseball 工具，用于生成 matplotlib 图表并返回 base64 编码图像
    • pybaseball_supp_tools.py - 用于连接 FanGraphs、Baseball Reference 和其他数据源的补充 pybaseball 函数
  • utils/ - 工具模块
    • logging_config.py - 日志配置
    • images.py - 与处理图表图像相关的函数
  • tests/ - 用于验证服务功能的测试套件
• pyproject.toml - 项目配置和依赖项
• .pre-commit-config.yaml - Pre-commit 钩子配置
• .github/ - GitHub Actions 工作流

工具

设置

1. 如果尚未安装 uv，请先安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 创建并激活虚拟环境：

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. 安装依赖项：

uv pip install -e .

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 MLB Stats Server：

npx -y @smithery/cli install @etweisberg/mlb-mcp --client claude

运行测试

此项目包含全面的 pytest 测试，用于验证 MCP 服务的功能：

uv run pytest -v

测试会验证所有 MLB StatsAPI 工具是否能通过 MCP 协议正常工作，包括建立连接、发起 API 调用和处理响应。

环境变量

此项目使用存储在 .env 中的环境变量来配置设置。

使用 ANTHROPIC_API_KEY 启用 MCP 服务。

日志配置

MLB Stats MCP Server 支持通过环境变量配置日志：

• MLB_STATS_LOG_LEVEL - 设置日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• MLB_STATS_LOG_FILE - 日志文件路径（未设置时，日志会写入 stderr）

日志会按设计写入 stderr，而不是 stdout：在 stdio 传输模式下， stdout 承载 JSON-RPC 流，向其中打印任何其他内容都会破坏该流。

HTTP 传输

使用 python -m mlb_stats_mcp.server --http 通过 HTTP 运行服务。它会 监听 $PORT（默认值为 8081），并在 /mcp 提供 MCP 服务。

默认情况下，服务接受任何 Host 和任何 Origin，因此远程部署开箱即用。要限制访问，可将任一变量设为 以逗号分隔的列表：

• MLB_STATS_ALLOWED_HOSTS - 接受的 Host 标头值。设置此项后 会启用 DNS 重绑定防护；其他主机的请求会被拒绝，并返回 421。条目可用 :* 结尾以允许任意端口，例如 localhost:*。
• MLB_STATS_ALLOWED_ORIGINS - 接受的 Origin 值，用于 CORS；在设置 MLB_STATS_ALLOWED_HOSTS 时， 也会据此拒绝其他来源，并返回 403。始终允许不带 Origin 标头的请求。

锁定部署时请同时设置两者；只指定主机名会拒绝所有基于浏览器的客户端。

Claude Desktop 集成

要将此 MCP 服务连接到 Claude Desktop，请在 claude_desktop_config.json 文件中添加配置。以下是配置模板：

"mcp-baseball-stats": {
  "command": "{PATH_TO_UV}",
  "args": [
    "--directory",
    "{PROJECT_DIRECTORY}",
    "run",
    "python",
    "-m",
    "mlb_stats_mcp.server"
  ],
  "env": {
    "MLB_STATS_LOG_FILE": "{LOG_FILE_PATH}",
    "MLB_STATS_LOG_LEVEL": "DEBUG"
  }
}

替换以下占位符：

• {PATH_TO_UV}：uv 安装路径（例如，~/.local/bin/uv）
• {PROJECT_DIRECTORY}：项目目录的路径
• {LOG_FILE_PATH}：日志文件的存储路径

使用的技术

• mcp[cli] - 用于定义工具的 Machine-Learning Chat Protocol
• mlb-statsapi - MLB Stats API 的 Python 封装
• httpx - 用于发送 API 请求的 HTTP 客户端
• pytest 和 pytest-asyncio - 测试框架
• uv - 快速的 Python 包管理器和安装程序

代码检查

此项目使用 Ruff 进行代码检查和格式化，并通过 pre-commit 钩子确保代码质量。

设置 Pre-commit 钩子

1. 安装 pre-commit：

pip install pre-commit

2. 初始化 pre-commit 钩子：

pre-commit install

现在，每当你提交代码时，代码检查都会自动运行。你也可以手动运行：

pre-commit run --all-files

代码检查配置

代码检查规则在 pyproject.toml 文件的 [tool.ruff] 部分中配置。此项目遵循 PEP 8 风格指南，并做了一些自定义调整。

CI 集成

GitHub Actions 工作流会在所有拉取请求以及推送到 main 分支时自动运行测试、代码检查和 pre-commit 检查。