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问题跟踪器。