JinDaGe - mlb-mcp MCP Details

article

README

🚀 MLB Stats MCP Server

MLB Stats MCP Server 是一个 Python 项目，它创建了一个模型上下文协议（MCP）服务器。该服务器可通过美国职业棒球大联盟（MLB）统计数据 API 以及 pybaseball 库，访问 MLB 的统计数据，涵盖了投球数据、Fangraphs 数据和棒球参考统计数据等。此服务器为棒球统计数据提供了结构化的 API 访问方式，可与支持 MCP 的客户端配合使用。

🚀 快速开始

项目结构

mlb_stats_mcp/ - 主包目录
- server.py - 核心 MCP 服务器实现
- tools/ - MCP 工具实现
  - mlb_statsapi_tools.py - MLB 统计数据 API 工具定义
  - statcast_tools.py - 投球数据工具定义
  - pybaseball_plotting_tools.py - 额外的 pybaseball 工具，用于生成 matplotlib 绘图并返回 base64 编码的图像
  - pybaseball_supp_tools.py - 补充的 pybaseball 函数，用于与 Fangraphs、棒球参考资料和其他数据源进行交互
- utils/ - 实用模块
  - logging_config.py - 日志配置
  - images.py - 与处理绘图图像相关的函数
- tests/ - 用于验证服务器功能的测试套件
pyproject.toml - 项目配置和依赖项
.pre-commit-config.yaml - 预提交钩子配置
.github/ - GitHub Actions 工作流

📦 安装指南

常规安装

若尚未安装 uv，请执行以下命令：

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

创建并激活虚拟环境：

uv venv
source .venv/bin/activate  # 在 Unix/macOS 系统上
# 或者
.venv\Scripts\activate  # 在 Windows 系统上

安装依赖项：

uv pip install -e .

通过 Smithery 安装

若要通过 Smithery 自动为 Claude Desktop 安装 MLB Stats Server，请执行以下命令：

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

运行测试

项目包含了用于 MCP 服务器功能的全面 pytest 测试：

uv run pytest -v

这些测试会验证所有 MLB 统计数据 API 工具是否能与 MCP 协议正常配合使用，包括建立连接、进行 API 调用和处理响应等操作。

🔧 技术细节

环境变量

项目使用存储在 .env 文件中的环境变量来配置设置。使用 ANTHROPIC_API_KEY 来启用 MCP 服务器。

日志配置

MLB Stats MCP 服务器支持通过环境变量进行可配置的日志记录：

MLB_STATS_LOG_LEVEL - 设置日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）
MLB_STATS_LOG_FILE - 日志文件的路径（若未设置，则将日志输出到标准输出）

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] - 用于工具定义的机器学习聊天协议
mlb-statsapi - MLB 统计数据 API 的 Python 包装器
httpx - 用于进行 API 请求的 HTTP 客户端
pytest 和 pytest-asyncio - 测试框架
uv - 快速的 Python 包管理器和安装程序

代码检查

本项目使用 Ruff 进行代码检查和格式化，并通过预提交钩子确保代码质量。

设置预提交钩子

安装预提交工具：

pip install pre-commit

初始化预提交钩子：

pre-commit install

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

pre-commit run --all-files

代码检查配置

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

CI 集成

GitHub Actions 工作流会在所有拉取请求和推送到主分支的操作上自动运行测试、代码检查和预提交检查。

mlb-mcp