Mlb MCP

🚀 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 工作流

📦 安裝指南

常規安裝

1. 若尚未安裝 uv，請執行以下命令：

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

2. 創建並激活虛擬環境：

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

3. 安裝依賴項：

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 進行代碼檢查和格式化，並通過預提交鉤子確保代碼質量。

設置預提交鉤子

1. 安裝預提交工具：

pip install pre-commit

2. 初始化預提交鉤子：

pre-commit install

現在，每當提交代碼時，代碼檢查將自動運行。你也可以手動運行：

pre-commit run --all-files

代碼檢查配置

代碼檢查規則在 pyproject.toml 文件的 [tool.ruff] 部分進行配置。項目遵循 PEP 8 風格指南，並進行了一些自定義設置。

CI 集成

GitHub Actions 工作流會在所有拉取請求和推送到主分支的操作上自動運行測試、代碼檢查和預提交檢查。