Nba Player Stats MCP

🚀 NBA球員數據MCP服務器

本服務器基於Model Context Protocol (MCP)，專注於從basketball-reference.com獲取全面的NBA球員數據。它提供了豐富的球員統計信息，包括職業生涯數據、賽季對比、高級指標、投籃數據等。

🚀 快速開始

從PyPI安裝

pip install nba-player-stats-mcp

從源代碼安裝

1. 克隆倉庫：

git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp

2. 安裝依賴：

pip install -r requirements.txt

啟動服務器

# 如果從PyPI安裝
nba-player-stats-server

# 如果從源代碼運行
python src/server.py

配置Claude Desktop

{
  "mcpServers": {
    "nba-player-stats": {
      "command": "python",
      "args": ["path/to/basketball/src/server.py"],
      "cwd": "path/to/basketball"
    }
  }
}

✨ 主要特性

本MCP服務器提供了三個層次的NBA球員數據統計工具：

第一層：核心統計（工具1 - 10）

• 職業生涯數據：包含逐賽季細分的完整職業生涯統計信息
• 賽季數據：特定賽季的詳細數據，包括季後賽
• 場均數據：傳統的場均統計信息
• 總計數據：賽季和職業生涯的總計數據（非平均值）
• 每36分鐘數據：經過節奏調整的每36分鐘統計信息
• 高級指標：球員效率值（PER）、真實命中率（TS%）、勝利貢獻值（WS）、正負值（BPM）、替代球員價值（VORP）等效率指標
• 球員對比：兩名球員的並排對比
• 投籃數據：詳細的投籃命中率和出手量統計信息
• 季後賽表現：完整的季後賽數據，並與常規賽進行對比
• 職業生涯亮點：最佳賽季、里程碑和成就

第二層：深度分析（工具11 - 17）

• 比賽記錄：逐場比賽的統計信息，用於詳細分析
• 特定數據查詢：獲取任何賽季的單個數據（例如，“斯蒂芬·庫裡2018年的三分命中率”）
• 獎項與投票：最有價值球員（MVP）、最佳防守球員（DPOY）等獎項的投票排名
• 對陣特定球隊數據：職業生涯對陣特定球隊的表現
• 月度數據：按月份細分的表現
• 關鍵數據：關鍵時刻和高壓情況下的表現
• 季後賽詳情：逐年的季後賽表現

第三層：超深度分析（工具18 - 23）

• 職業生涯趨勢：逐年的進步和衰退分析
• 高光比賽：職業生涯最高分、40分以上比賽、三雙等
• 特定場景數據：主場/客場、背靠背比賽、勝負情況等
• 季度數據：第四季度的表現和加時賽數據
• 里程碑跟蹤：職業生涯里程碑的進展和預測
• 歷史排名：球員在NBA歷史上的排名

其他特性

• 球員頭像：basketball-reference.com的球員頭像URL
• 多種數據類型：場均數據（PER_GAME）、總計數據（TOTALS）、每分鐘數據（PER_MINUTE）、每回合數據（PER_POSS）、高級數據（ADVANCED）
• 歷史數據：可訪問歷史賽季和職業生涯進展數據
• 23個工具：全面覆蓋各種可能的球員數據查詢

📦 安裝指南

前提條件

• Python 3.8 或更高版本
• pip包管理器

從PyPI安裝

這是安裝NBA球員數據MCP服務器最簡單的方法：

pip install nba-player-stats-mcp

從源代碼安裝

如果需要進行開發或獲取最新更改：

1. 克隆倉庫：

git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp

2. 創建虛擬環境（推薦）：

python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

3. 以開發模式安裝：

pip install -e .
# 或者安裝開發依賴
pip install -e ".[dev]"

💻 使用示例

啟動服務器

# 如果從PyPI安裝
nba-player-stats-server

# 如果從源代碼運行
python src/server.py

Python使用示例

# 首先導入修復模塊
import fix_basketball_reference
from basketball_reference_scraper.players import get_stats

# 獲取勒布朗的職業生涯場均數據
stats = get_stats('LeBron James', stat_type='PER_GAME', ask_matches=False)

# 獲取特定賽季的數據
stats_2023 = stats[stats['SEASON'] == '2022-23']

# 獲取季後賽數據
playoff_stats = get_stats('LeBron James', stat_type='PER_GAME', playoffs=True, ask_matches=False)

更多詳細示例請參考example_usage.py。

📚 詳細文檔

可用工具

第一層：核心統計工具

1. get_player_career_stats：獲取NBA球員的完整職業生涯統計信息。

   • 參數：
     • player_name（字符串，必填）：球員姓名（例如，“LeBron James”）
     • stat_type（字符串，可選）：數據類型 - “PER_GAME”、“TOTALS”、“PER_MINUTE”、“PER_POSS”、“ADVANCED”

2. get_player_season_stats：獲取特定賽季的統計信息。

   • 參數：
     • player_name（字符串，必填）：球員姓名
     • season（整數，必填）：賽季年份（例如，2023表示2022 - 23賽季）
     • stat_type（字符串，可選）：數據類型
     • include_playoffs（布爾值，可選）：如果可用，是否包含季後賽數據

3. get_player_advanced_stats：獲取高級統計信息（PER、TS%、WS、BPM、VORP等）。

   • 參數：
     • player_name（字符串，必填）：球員姓名
     • season（整數，可選）：特定賽季，或None表示所有賽季

4. get_player_per36_stats：獲取每36分鐘的統計信息（經過節奏調整）。

   • 參數：
     • player_name（字符串，必填）：球員姓名
     • season（整數，可選）：特定賽季，或None表示所有賽季

5. compare_players：比較兩名NBA球員的統計信息。

   • 參數：
     • player1_name（字符串，必填）：第一名球員的姓名
     • player2_name（字符串，必填）：第二名球員的姓名
     • stat_type（字符串，可選）：要比較的數據類型
     • season（整數，可選）：特定賽季，或None表示職業生涯對比

6. get_player_shooting_splits：獲取詳細的投籃統計信息和細分數據。

   • 參數：
     • player_name（字符串，必填）：球員姓名
     • season（整數，可選）：特定賽季，或None表示職業生涯數據

7. get_player_totals：獲取總計統計信息（非平均值）。

   • 參數：
     • player_name（字符串，必填）：球員姓名
     • season（整數，可選）：特定賽季，或None表示職業生涯總計

8. get_player_playoff_stats：獲取季後賽統計信息，並與常規賽進行對比。

   • 參數：
     • player_name（字符串，必填）：球員姓名
     • stat_type（字符串，可選）：數據類型

9. get_player_headshot_url：獲取basketball-reference.com的球員頭像URL。

   • 參數：
     • player_name（字符串，必填）：球員姓名

10. get_player_career_highlights：獲取職業生涯亮點和成就。

    • 參數：
      • player_name（字符串，必填）：球員姓名

第二層：深度分析工具

11. get_player_game_log：獲取特定賽季的逐場比賽統計信息。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • season（整數，必填）：賽季年份（例如，2024）
      • playoffs（布爾值，可選）：是否獲取季後賽比賽記錄
      • date_from（字符串，可選）：開始日期，格式為'YYYY - MM - DD'
      • date_to（字符串，可選）：結束日期，格式為'YYYY - MM - DD'

12. get_player_specific_stat：獲取球員在給定賽季的特定統計信息。非常適合回答諸如“斯蒂芬·庫裡2018年的三分命中率是多少？”之類的問題。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • stat_name（字符串，必填）：特定數據（例如，“PTS”、“3P%”、“PER”）
      • season（整數，必填）：賽季年份

13. get_player_vs_team_stats：獲取職業生涯對陣特定球隊的統計信息。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • team_abbreviation（字符串，必填）：球隊代碼（例如，“GSW”、“LAL”）
      • stat_type（字符串，可選）：數據類型

14. get_player_awards_voting：獲取獎項和投票歷史。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • award_type（字符串，可選）：“MVP”、“DPOY”、“ROY”、“SMOY”、“MIP”

15. get_player_monthly_splits：獲取按月份細分的統計信息。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • season（整數，必填）：賽季年份
      • month（字符串，可選）：特定月份，或None表示所有月份

16. get_player_clutch_stats：獲取關鍵時刻的表現。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • season（整數，可選）：特定賽季，或None表示職業生涯

17. get_player_playoffs_by_year：獲取特定年份的詳細季後賽統計信息。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • season（整數，必填）：賽季年份

第三層：超深度分析工具

18. get_player_career_trends：分析職業生涯趨勢和進展，包括逐年變化和衰退/進步模式。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • stat_name（字符串，可選）：要分析趨勢的數據（默認：“PTS”）
      • window_size（整數，可選）：移動平均的年數（默認：3）

19. get_player_game_highs：獲取職業生涯高光比賽和里程碑表現（40分以上比賽、50分以上比賽、三雙）。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • threshold_points（整數，可選）：高分比賽的得分閾值（默認：40）
      • include_triple_doubles（布爾值，可選）：是否統計三雙比賽

20. get_player_situational_splits：獲取特定場景下的表現細分數據，包括主場/客場、背靠背比賽、勝負情況等。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • season（整數，可選）：特定賽季，或None表示職業生涯
      • split_type（字符串，可選）：“home_away”、“rest_days”、“monthly”、“win_loss”

21. get_player_quarter_stats：獲取每季度的表現，特別是第四季度和加時賽的數據。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • season（整數，可選）：特定賽季，或None表示職業生涯
      • quarter（字符串，可選）：“1st”、“2nd”、“3rd”、“4th”、“OT”或“all”

22. get_player_milestone_tracker：跟蹤職業生涯里程碑的進展，並進行成就預測。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • milestone_type（字符串，可選）：“points”、“assists”、“rebounds”、“3pm”、“games”

23. get_player_rankings：獲取球員在各個類別中的歷史排名。

    • 參數：
      • player_name（字符串，必填）：球員姓名
      • category（字符串，可選）：“points”、“assists”、“rebounds”、“3pm”、“steals”、“blocks”

示例問題

本MCP服務器可以回答以下示例問題：

基本查詢（第一層）

1. 職業生涯概述：“勒布朗·詹姆斯的職業生涯統計信息有哪些？”
2. 賽季對比：“斯蒂芬·庫裡在2016賽季的表現如何？”
3. 球員對比：“比較邁克爾·喬丹和勒布朗·詹姆斯的職業生涯數據”
4. 投籃分析：“斯蒂芬·庫裡的職業生涯投籃命中率是多少？”
5. 高級指標：“尼古拉·約基奇在2023年的球員效率值（PER）是多少？”
6. 季後賽表現：“科懷·倫納德的季後賽數據與常規賽相比如何？”
7. 職業生涯里程碑：“卡里姆·阿卜杜爾 - 賈巴爾的職業生涯亮點有哪些？”
8. 每36分鐘數據：“揚尼斯·阿德託昆博的每36分鐘數據是多少？”

深度分析查詢（第二層）

9. 特定數據：“斯蒂芬·庫裡在2018年的三分命中率是多少？”
10. 得分查詢：“斯蒂芬·庫裡在2024年的場均得分是多少？”
11. 獎項：“勒布朗·詹姆斯在2020年的MVP投票中排名第幾？”
12. 比賽記錄：“展示達米安·利拉德2021年季後賽的比賽記錄”
13. 對陣特定球隊：“凱文·杜蘭特職業生涯對陣湖人隊的數據如何？”
14. 月度數據：“傑森·塔圖姆在2023年12月的表現如何？”
15. 關鍵時刻數據：“凱里·歐文職業生涯的關鍵時刻數據如何？”
16. 季後賽年份：“吉米·巴特勒在2020年季後賽的表現如何？”

超深度分析查詢（第三層）

17. 職業生涯趨勢：“勒布朗·詹姆斯是否隨著年齡增長而狀態下滑？”
18. 高光比賽：“凱文·杜蘭特職業生涯有多少場40分以上的比賽？”
19. 主場/客場表現：“喬爾·恩比德在主場和客場的表現如何？”
20. 第四季度數據：“盧卡·東契奇在第四季度的場均得分是多少？”
21. 里程碑跟蹤：“勒布朗·詹姆斯何時能突破40000分？”
22. 歷史排名：“斯蒂芬·庫裡在三分命中數的歷史排名如何？”
23. 特定場景表現：“揚尼斯·阿德託昆博在背靠背比賽中的表現如何？”
24. 季度細分：“達米安·利拉德的得分中有多少百分比來自第四季度？”

數據類型解釋

• PER_GAME：傳統的場均數據（得分、籃板、助攻等）
• TOTALS：賽季或職業生涯的總計數據
• PER_MINUTE：每36分鐘的數據（根據上場時間進行標準化）
• PER_POSS：每100回合的數據（根據比賽節奏進行標準化）
• ADVANCED：高級指標（PER、TS%、WS、BPM、VORP等）

關鍵數據術語表

• PER：球員效率值
• TS%：真實命中率
• WS：勝利貢獻值
• BPM：正負值
• VORP：替代球員價值
• eFG%：有效命中率
• USG%：使用率
• ORtg：進攻效率（每100回合得分）
• DRtg：防守效率（每100回合失分）
• 3P%：三分命中率
• FT%：罰球命中率
• AST%：助攻率
• REB%：籃板率

🔧 技術細節

籃球數據抓取器修復

重要提示：basketball_reference_scraper庫與當前basketball-reference.com網站結構存在兼容性問題。本服務器包含了針對這些問題的自動修復。

修復的問題

1. 表格ID更改：Basketball Reference更新了他們的HTML表格ID
   • per_game → per_game_stats
   • totals → totals_stats
   • per_minute → per_minute_stats
2. Pandas兼容性：修復了pd.read_html()的棄用警告
3. 錯誤處理：改進了對缺失數據和邊緣情況的處理

這些修復在服務器啟動時通過fix_basketball_reference.py模塊自動應用。

完整修復細節

修復涉及更新basketball_reference_scraper/players.py文件：

1. 添加StringIO導入（在BeautifulSoup導入之後）：

from io import StringIO

2. 更新表格ID映射（在get_stats函數中）：

# 將舊的表格ID映射到新的ID
table_id_map = {
    'per_game': 'per_game_stats',
    'totals': 'totals_stats',
    'per_minute': 'per_minute_stats',
    'per_poss': 'per_poss_stats',
    'advanced': 'advanced'
}

3. 修復pandas read_html棄用問題：

# 替換：df = pd.read_html(table)[0]
df = pd.read_html(StringIO(table))[0]

4. 處理缺失的職業生涯行：

career_rows = df[df['SEASON']=='Career'].index
if len(career_rows) > 0:
    career_index = career_rows[0]
    # ... 其餘邏輯

如果要將這些修復貢獻回原始庫，請參閱貢獻指南部分。

開發指南

設置開發環境

1. 創建虛擬環境：

python -m venv venv
source venv/bin/activate

2. 安裝依賴：

pip install -r requirements.txt

測試

# 運行所有測試
pytest

# 運行測試並生成覆蓋率報告
pytest --cov=src --cov-report=html

# 運行特定測試
pytest tests/test_integration.py -v

手動測試

測試修復模塊：

python example_usage.py

常見測試用例

1. 球員姓名變化：
   • 精確匹配：“LeBron James” ✓
   • 大小寫敏感：“lebron james” ✗
   • 部分姓名：“LeBron” ✗
2. 邊緣情況：
   • 退役球員
   • 沒有季後賽經驗的球員
   • 歷史球員（1973年之前的高級數據）

代碼風格指南

1. Python風格：遵循PEP 8
2. 錯誤處理：始終捕獲特定異常
3. 數據處理：在訪問數據之前檢查是否為空

擴展服務器

要添加新工具：

1. 在server.py中創建函數：

@mcp.tool()
async def get_player_new_stat(
    player_name: str,
    **kwargs
) -> Dict[str, Any]:
    """工具描述"""
    try:
        # 實現邏輯
        pass
    except Exception as e:
        logger.error(f"Error: {e}")
        return {"error": str(e)}

2. 使用各種球員進行全面測試
3. 更新本README文檔，添加新工具的文檔

已知問題

正常工作的功能 ✅

• 所有球員統計工具在應用修復後均可正常工作
• 球員頭像URL可靠

限制 ⚠️

1. 球員姓名：必須與basketball-reference.com格式完全匹配
   • ✓ “LeBron James”
   • ✗ “Lebron” 或 “lebron james”
2. 歷史數據：某些功能對於較舊賽季的數據可能有限
   • 1973 - 74賽季之前沒有高級數據
   • 早期職業生涯的某些投籃數據缺失
3. 庫的限制：底層的basketball_reference_scraper存在以下問題：
   • 沒有積極維護
   • 錯誤處理不一致
   • 文檔有限

故障排除

“未找到表格”錯誤

• 原因：網站結構更改
• 修復：由fix_basketball_reference.py自動應用

未找到球員

• 原因：姓名格式不正確
• 解決方案：使用basketball-reference.com上的精確姓名

結果為空

• 原因：球員在請求的類型/賽季沒有數據
• 解決方案：檢查球員的職業生涯跨度和數據可用性

測試

運行測試套件：

# 安裝開發依賴
pip install -e ".[dev]"

# 運行測試
pytest

# 運行測試並生成覆蓋率報告
pytest --cov=src --cov-report=html

貢獻

1. 分叉倉庫
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打開拉取請求

貢獻修復到basketball_reference_scraper

要將我們的修復貢獻回原始庫：

1. 分叉：https://github.com/vishaalagartha/basketball_reference_scraper
2. 應用fix_basketball_reference.py中的更改
3. 使用各種球員進行全面測試
4. 提交拉取請求：“Fix table parsing for updated basketball-reference.com structure”

變更日誌

版本0.3.0（最新）

• 添加了第三層超深度分析工具（6個新工具）
• 職業生涯趨勢分析，包括逐年進展
• 高光比賽和里程碑跟蹤（40分以上比賽、三雙）
• 特定場景細分（主場/客場、背靠背比賽、勝負情況）
• 每季度表現分析
• 里程碑預測和歷史排名
• 現在三個層次共有23個工具

版本0.2.0

• 添加了第二層深度分析工具（7個新工具）
• 比賽記錄和特定數據查詢
• 獎項和投票歷史支持
• 對陣球隊統計信息
• 月度和時間細分
• 關鍵時刻表現指標
• 增強的逐年季後賽分析

版本0.1.0

• 初始版本，包含10個核心球員統計工具
• 與basketball-reference.com的兼容性修復
• 職業生涯、賽季和高級統計信息

📄 許可證

本項目採用MIT許可證 - 詳情請參閱LICENSE文件。

致謝

• 數據來源於 basketball-reference.com
• 基於 basketball_reference_scraper 庫構建
• 實現了 Model Context Protocol
• 使用了 FastMCP 框架

支持

如有問題和功能請求，請使用 GitHub問題跟蹤器。