使用说明

NBA球员统计MCP服务器

一个专注的模型上下文协议（MCP）服务器，从basketball-reference.com提供全面的NBA球员统计数据。该服务器专门提供详细的球员统计数据，包括职业统计数据、赛季比较、高级指标、投篮统计数据等。

特性

此MCP服务器提供跨三层深度的专业NBA球员统计工具：

第1层：核心统计（工具1-10）

职业统计：完整的职业统计数据，按季节细分
季节统计：包括季后赛在内的特定赛季的详细统计数据
每场比赛平均值：传统每场比赛统计数据
总计统计：赛季和职业生涯总计（非平均值）
每36分钟：每36分钟调整一次的统计数据
高级指标：PER、TS%、WS、BPM、VORP和其他效率指标
玩家比较：两个玩家之间的并排比较
射击分裂：详细的射击百分比和体积统计
季后赛表现：完整的季后赛统计数据，并与常规赛进行比较
职业亮点：最佳赛季、里程碑和成就

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

游戏日志：用于详细分析的逐个游戏统计数据
特定统计查询：获取任何季节的个人统计数据（例如，“斯蒂芬2018年的3P%”）
奖项与投票：MVP、DPOY和其他奖项投票职位
与团队统计数据：针对特定团队的职业表现
每月拆分：按月份分列的业绩
离合器统计数据：在近距离比赛和压力情况下的表现
季后赛详细信息：季后赛逐年表现

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

职业发展趋势：同比增长和下降分析
游戏高潮：职业生涯新高，40+分的比赛，三双
情境性分裂：主场/客场、休息日、输赢情况
季度统计数据：第四季度专业化和离合器性能
里程碑跟踪：在有预测的记录方面取得进展
历史排名：球员在NBA历史上的排名

附加功能

球员头球：Basketball-reference.com球员头像网址
多种统计类型: PER_GAME，TOTALS，PER_MINUTE，PER_POSS，ADVANCED
历史数据：了解历史季节和职业发展
23总工具：全面覆盖所有可能的玩家统计查询

快速开始

从PyPI安装

pip install nba-player-stats-mcp

从源代码安装

克隆存储库：

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

安装依赖项：

pip install -r requirements.txt

运行服务器

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

配置Claude桌面

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

安装

先决条件

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

从PyPI安装

安装NBA球员统计MCP服务器的最简单方法：

pip install nba-player-stats-mcp

从源代码安装

为了开发或获取最新更改：

克隆存储库：

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

创建虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

在开发模式下安装：

pip install -e .
# Or with development dependencies
pip install -e ".[dev]"

用法

启动服务器

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Python使用示例

# Import the fix first
import fix_basketball_reference
from basketball_reference_scraper.players import get_stats

# Get LeBron's career per-game stats
stats = get_stats('LeBron James', stat_type='PER_GAME', ask_matches=False)

# Get specific season
stats_2023 = stats[stats['SEASON'] == '2022-23']

# Get playoff stats
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 （string，必填）：玩家姓名
season （整数，必填）：季节年份（例如，2022-23年为2023年）
stat_type （字符串，可选）：统计数据类型
include_playoffs （布尔值，可选）：包括季后赛统计数据（如果可用）

3. `get_player_advanced_stats`

获取高级统计数据（PER、TS%、WS、BPM、VORP等）。

参数：

player_name （string，必填）：玩家姓名
season （整数，可选）：特定季节，或所有季节均为无

4. `get_player_per36_stats`

获取每36分钟的统计数据（调整速度）。

参数：

player_name （string，必填）：玩家姓名
season （整数，可选）：特定季节，或所有季节均为无

5. `compare_players`

比较两名NBA球员的统计数据。

参数：

player1_name （字符串，必填）：第一个玩家的名字
player2_name （字符串，必填）：第二个玩家的名字
stat_type （字符串，可选）：要比较的统计数据类型
season （整数，可选）：特定季节，或无用于职业比较

6. `get_player_shooting_splits`

获取详细的拍摄统计数据和分割。

参数：

player_name （string，必填）：玩家姓名
season （整数，可选）：特定赛季，或无职业统计数据

7. `get_player_totals`

获取总统计数据（而不是平均值）。

参数：

player_name （string，必填）：玩家姓名
season （整数，可选）：特定季节，或职业生涯总计为无

8. `get_player_playoff_stats`

通过常规赛比较获得季后赛统计数据。

参数：

player_name （string，必填）：玩家姓名
stat_type （字符串，可选）：统计数据类型

9. `get_player_headshot_url`

获取basketball-reference.com头像URL。

参数：

player_name （string，必填）：玩家姓名

10. `get_player_career_highlights`

获得职业亮点和成就。

参数：

player_name （string，必填）：玩家姓名

第二层：深度分析工具

11. `get_player_game_log`

获取特定赛季的每场比赛统计数据。

参数：

player_name （string，必填）：玩家姓名
season （整数，必填）：季节年份（例如2024年）
playoffs （布尔值，可选）：是否获取季后赛比赛日志
date_from （字符串，可选）：“YYYY-MM-DD”格式的开始日期
date_to （字符串，可选）：结束日期，格式为“YYYY-MM-DD”

12. `get_player_specific_stat`

获取特定赛季球员的具体统计数据。非常适合回答“斯蒂芬2018年的3P%是多少？”

参数：

player_name （string，必填）：玩家姓名
stat_name （字符串，必填）：具体统计数据（例如，“PTS”、“3P%”、“PER”）
season （整数，必填）：季节年份

13. `get_player_vs_team_stats`

获取特定团队的职业统计数据。

参数：

player_name （string，必填）：玩家姓名
team_abbreviation （字符串，必填）：团队代码（例如“GSW”、“LAL”）
stat_type （字符串，可选）：统计数据类型

14. `get_player_awards_voting`

获取奖项和投票历史记录。

参数：

player_name （string，必填）：玩家姓名
award_type （字符串，可选）：“MVP”、“DPOY”、“ROY”、”SMOY“、”MIP“

15. `get_player_monthly_splits`

获取按月细分的统计数据。

参数：

player_name （string，必填）：玩家姓名
season （整数，必填）：季节年份
month （字符串，可选）：特定月份或全部为无

16. `get_player_clutch_stats`

在离合器情况下获得性能。

参数：

player_name （string，必填）：玩家姓名
season （整数，可选）：特定季节或无职业

17. `get_player_playoffs_by_year`

获取特定年份的详细季后赛统计数据。

参数：

player_name （string，必填）：玩家姓名
season （整数，必填）：季节年份

第三层：超深度分析工具

18. `get_player_career_trends`

分析职业趋势和进展，包括同比变化和下降/改善模式。

参数：

player_name （string，必填）：玩家姓名
stat_name （字符串，可选）：用于分析趋势的统计数据（默认值：“PTS”）
window_size （整数，可选）：移动平均线年份（默认值：3）

19. `get_player_game_highs`

获得职业生涯最高的比赛和里程碑式的表现（40+分、50+分、三双）。

参数：

player_name （string，必填）：玩家姓名
threshold_points （整数，可选）：高分游戏的得分阈值（默认值：40）
include_triple_doubles （布尔值，可选）：是否估计三双游戏

20. `get_player_situational_splits`

获取情景表现分割，包括主场/客场、休息日和输赢情况。

参数：

player_name （string，必填）：玩家姓名
season （整数，可选）：特定季节或无职业
split_type （字符串，可选）：“home_away”、“rest_days”、“monthly”、“win_loss”

21. `get_player_quarter_stats`

获取每季度的表现，尤其是第四季度和加班统计数据。

参数：

player_name （string，必填）：玩家姓名
season （整数，可选）：特定季节或无职业
quarter （字符串，可选）：“第一”、“第二”、“三”、“四”、“OT”或“全部”

22. `get_player_milestone_tracker`

跟踪职业里程碑的进展，并对成就进行预测。

参数：

player_name （string，必填）：玩家姓名
milestone_type （字符串，可选）：“得分”、“助攻”、“篮板”、“下午3点”、“比赛”

23. `get_player_rankings`

获取不同类别玩家的历史排名。

参数：

player_name （string，必填）：玩家姓名
category （字符串，可选）：“得分”、“助攻”、“篮板”、“下午3点”、“抢断”、“盖帽”

例子

以下是此MCP服务器可以回答的一些示例问题：

基本查询（第1层）

职业概述：“勒布朗·詹姆斯的职业生涯统计数据是多少？”
季节比较“斯蒂芬·库里在2016赛季的表现如何？”
球员比较：“比较迈克尔·乔丹和勒布朗·詹姆斯的职业生涯数据”
射击分析“库里的职业生涯投篮命中率是多少？”
高级指标“Nikola Jokić2023年的PER是多少？”
季后赛表现：“科怀·伦纳德的季后赛数据与常规赛相比如何？”
职业里程碑：“卡里姆·阿卜杜勒-贾巴尔的职业生涯亮点是什么？”
Per-36统计数据“Giannis Antetokounmpo每36分钟的统计数据是什么？”

深度分析查询（第2层）

具体统计“斯蒂芬·库里在2018年的三分球命中率是多少？”
积分查询“斯蒂芬·库里在2024年的平均得分是多少？”
奖项：“勒布朗·詹姆斯在2020年的MVP投票中是在哪里完成的？”
游戏日志：“给我看看达米安·利拉德2021年季后赛的比赛记录”
Vs团队：“凯文·杜兰特对阵湖人队的职业生涯数据是什么？”
每月“Jayson Tatum在2023年12月的表现如何？”
离合器：“凯里·欧文职业生涯的关键数据是什么？”
季后赛年“吉米·巴特勒在2020年季后赛中的表现如何？”

超深度分析查询（第3层）

职业发展趋势：“勒布朗·詹姆斯会随着年龄的增长而衰退吗？”
里程碑游戏“凯文·杜兰特有多少场40分的比赛？”
主页/离开“Joel Embiid在主场和客场的表现如何？”
第四季度“卢卡·唐契奇在第四节的平均得分是多少？”
里程碑跟踪：“勒布朗什么时候能拿到40000分？”
历史排名“库里的三分球命中率在历史上排名哪？”
情境的：“Giannis背对背的表现如何？”
季度细分：“Dame的分数中有多少是第四名？”

统计类型说明

PER_GAME：传统每场比赛的平均得分（得分、篮板、助攻等）
总计：一个赛季或职业生涯的总统计数据
每分钟：每36分钟统计数据（按比赛时间标准化）
PER_POSS：每100次拥有统计数据（按速度标准化）
高级：高级指标（PER、TS%、WS、BPM、VORP等）

关键统计术语表

每：球员效率评级
TS%：真实射击百分比
操作系统：赢取股份
每分钟节拍数：盒子加/减
VORP：价值高于替代球员
eFG百分比：有效现场目标百分比
美元%：使用率
ORtg：进攻等级（每100次进攻得分）
DRtg：防御等级（每100次进攻允许得分）
3P%：三分球命中率
FT%：罚球百分比
AST%：辅助百分比
REB%：回弹百分比

篮球参考刮刀修复

重要：The basketball_reference_scraper 图书馆与当前的篮球参考网站结构存在兼容性问题。此服务器包含针对这些问题的自动修复程序。

已修复的问题

表ID更改：Basketball Reference更新了他们的HTML表ID
- per_game → per_game_stats
- totals → totals_stats
- per_minute → per_minute_stats
Pandas兼容性：修复了弃用警告 pd.read_html()
错误处理：改进对缺失数据和边缘情况的处理

当服务器通过启动时，修复程序会自动应用 fix_basketball_reference.py 模块。

完整修复详细信息

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

添加StringIO导入 （导入BeautifulSoup后）：
```
from io import StringIO
```

更新表ID映射 （in get_stats 功能）：

# Map old table IDs to new ones
table_id_map = {
    'per_game': 'per_game_stats',
    'totals': 'totals_stats',
    'per_minute': 'per_minute_stats',
    'per_poss': 'per_poss_stats',
    'advanced': 'advanced'
}

修复pandas read_html弃用问题:

# Replace: df = pd.read_html(table)[0]
df = pd.read_html(StringIO(table))[0]

处理缺失的职业行:

career_rows = df[df['SEASON']=='Career'].index
if len(career_rows) > 0:
    career_index = career_rows[0]
    # ... rest of logic

要将这些修复程序贡献回原始库，请参阅贡献部分。

开发指南

设置开发环境

创建虚拟环境：

python -m venv venv
source venv/bin/activate

安装依赖项：
```
pip install -r requirements.txt
```

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test
pytest tests/test_integration.py -v

手动测试

测试修复模块：

python example_usage.py

常见测试用例

玩家名称变化:
- 精确匹配：“LeBron James”✓
- 案件敏感性：“lebron james”✗
- 部分名称：“LeBron”✗
边缘案例:
- 退役球员
- 没有季后赛经验的球员
- 历史球员（1973年前的高级统计数据）

代码风格指南

Python风格：遵循政治公众人物8
错误处理：始终捕获特定的异常
数据处理：访问前检查空结果

扩展服务器

要添加新工具，请执行以下操作：

在中创建函数 server.py:

@mcp.tool()
async def get_player_new_stat(
    player_name: str,
    **kwargs
) -> Dict[str, Any]:
    """Tool description"""
    try:
        # Implementation
        pass
    except Exception as e:
        logger.error(f"Error: {e}")
        return {"error": str(e)}

与各种玩家进行彻底测试
用新的工具文档更新此README

已知问题

工作特点✅

所有玩家统计工具在应用修复后都能正常运行
玩家头像URL工作可靠

局限性⚠️

玩家姓名：必须完全符合basketball-reference.com格式
- ✓ “勒布朗·詹姆斯”
- ✗ “勒布朗”或“勒布朗-詹姆斯”
历史数据：一些功能可能对旧季节的数据有限
- 1973-74年之前没有高级统计数据
- 职业生涯早期缺少一些投篮数据
图书馆限制：基础 basketball_reference_scraper 有：
- 无主动维护
- 错误处理不一致
- 文件有限

故障排除

“未找到表”错误

原因：网站结构已更改
修复：由Fix_basketball_reference.py自动应用

未找到玩家

原因：名称格式不正确
解决方案：使用basketball-reference.com中的确切名称

空结果

原因：玩家没有所请求类型/赛季的统计数据
解决方案：检查玩家的职业生涯和统计数据可用性

测试

运行测试套件：

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

贡献

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

对篮球的贡献修复_reference_scraper

要将我们的修复程序贡献回原始库：

叉子：https://github.com/vishaalagartha/basketball_reference_scraper
应用以下更改 fix_basketball_reference.py
与各种玩家进行彻底测试
提交PR：“修复更新的basketball-reference.com结构的表解析”

更新日志

版本0.3.0（最新）

添加了第3层超深度分析工具（6个新工具）
职业发展趋势分析
比赛高潮和里程碑追踪（40+分比赛，三双）
情景分割（主场/客场、休息日、输赢）
逐季度绩效分析
里程碑预测和历史排名
现在包括3层共23个工具

版本0.2.0

添加了第2层深度分析工具（7个新工具）
游戏日志和特定统计查询
奖项和投票历史支持
球队对决统计
月度和时间划分
离合器性能指标
增强季后赛逐年分析

版本0.1.0

初始版本包含10个核心玩家统计工具
Basketball-reference.com兼容性修复
职业、季节和高级统计数据

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

数据来源于篮球参考网
使用篮球参考资料_ craper 图书馆
实施模型上下文协议
用途 FastMCP 框架

支持

有关问题和功能请求，请使用 GitHub问题跟踪器.

使用说明

NBA球员统计MCP服务器

目录

特性

第1层：核心统计（工具1-10）

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

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

附加功能

快速开始

从PyPI安装

从源代码安装

运行服务器

配置Claude桌面

安装

先决条件

从PyPI安装

从源代码安装

用法

启动服务器

Python使用示例

可用工具

1. get_player_career_stats

2. get_player_season_stats

3. get_player_advanced_stats

4. get_player_per36_stats

5. compare_players

6. get_player_shooting_splits

7. get_player_totals

8. get_player_playoff_stats

9. get_player_headshot_url

10. get_player_career_highlights

第二层：深度分析工具

11. get_player_game_log

12. get_player_specific_stat

13. get_player_vs_team_stats

14. get_player_awards_voting

15. get_player_monthly_splits

16. get_player_clutch_stats

17. get_player_playoffs_by_year

第三层：超深度分析工具

18. get_player_career_trends

19. get_player_game_highs

20. get_player_situational_splits

21. get_player_quarter_stats

22. get_player_milestone_tracker

23. get_player_rankings

例子

基本查询（第1层）

深度分析查询（第2层）

超深度分析查询（第3层）

统计类型说明

关键统计术语表

篮球参考刮刀修复

已修复的问题

完整修复详细信息

开发指南

设置开发环境

测试

手动测试

常见测试用例

代码风格指南

扩展服务器

已知问题

工作特点✅

局限性⚠️

故障排除

测试

贡献

对篮球的贡献修复_reference_scraper

更新日志

版本0.3.0（最新）

版本0.2.0

版本0.1.0

许可证

致谢

支持

相关 MCP

梦幻足球数据服务

NBA数据MCP服务

网球天梯API服务

1. `get_player_career_stats`

2. `get_player_season_stats`

3. `get_player_advanced_stats`

4. `get_player_per36_stats`

5. `compare_players`

6. `get_player_shooting_splits`

7. `get_player_totals`

8. `get_player_playoff_stats`

9. `get_player_headshot_url`

10. `get_player_career_highlights`

11. `get_player_game_log`

12. `get_player_specific_stat`

13. `get_player_vs_team_stats`

14. `get_player_awards_voting`

15. `get_player_monthly_splits`

16. `get_player_clutch_stats`

17. `get_player_playoffs_by_year`

18. `get_player_career_trends`

19. `get_player_game_highs`

20. `get_player_situational_splits`

21. `get_player_quarter_stats`

22. `get_player_milestone_tracker`

23. `get_player_rankings`