技术文档摘要

🏀 NBA MCP 服务器

通过模型上下文协议访问全面的NBA统计数据。

这是一个提供实时和历史NBA数据访问的模型上下文协议（MCP）服务器，包括球员统计、比赛得分、球队信息和高级分析。

快速开始使用 Claude Desktop

1. 安装服务器：

# 使用 uvx（推荐 - 不需要安装）
uvx nba-stats-mcp

# 或者使用 pip
pip install nba-stats-mcp

# 或者从源码安装
git clone https://github.com/labeveryday/nba_mcp_server.git
cd nba_mcp_server
uv sync

2. 添加到你的 Claude Desktop 配置文件：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "nba-stats": {
      "command": "uvx",
      "args": ["nba-stats-mcp"]
    }
  }
}

或者如果你是从源码安装的：

{
  "mcpServers": {
    "nba-stats": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/nba_mcp_server/",
        "run",
        "nba-stats-mcp"
      ]
    }
  }
}

3. 重启 Claude Desktop

你可以询问的内容

• "显示今天的NBA比赛"
• "LeBron James本赛季的数据是什么？"
• "获取湖人队对阵勇士队的比赛得分"
• "本赛季得分最高的前10名是谁？"
• "显示所有时间助攻最多的球员"
• "凯尔特人队下次比赛是什么时候？"
• "获取Stephen Curry的投篮图表"
• "联赛中防守积极度最高的球员是谁？"
• "显示Giannis的职业荣誉"

可用工具（总共26个）

球员统计

• search_players - 按姓名查找球员
• get_player_info - 球员简介和详细信息
• get_player_season_stats - 当前/历史赛季统计
• get_player_career_stats - 职业生涯总计和平均值
• get_player_game_log - 比赛对比赛的表现
• get_player_awards - 所有奖项和荣誉
• get_player_hustle_stats - 抢断、挡拆、松球、篮板
• get_player_defense_stats - 对手在防守时的命中率
• get_player_advanced_stats - TS%，ORtg，DRtg，USG%，PIE

球队统计

• get_all_teams - 所有的30支NBA球队
• get_team_roster - 球队名单
• get_team_advanced_stats - 球队效率指标

实时比赛

• get_todays_scoreboard - 今天带有实时比分的比赛
• get_scoreboard_by_date - 特定日期的比赛
• get_game_details - 带有实时统计的详细比赛信息
• get_box_score - 包含球员统计的完整比赛得分表
• get_play_by_play - 完整的比赛实况数据
• get_game_rotation - 球员换人模式

联盟统计

• get_standings - 当前NBA排名
• get_league_leaders - 统计领先者（得分、助攻、篮板等）
• get_all_time_leaders - 所有时间的职业领先者
• get_league_hustle_leaders - 联盟中的积极度领先者
• get_schedule - 球队赛程（最多提前90天）
• get_season_awards - 季度MVP和其他主要奖项

射击分析

• get_shot_chart - 带有X/Y坐标的投篮位置
• get_shooting_splits - 根据区域和距离的投篮百分比

安装选项

使用 uv（推荐）

git clone https://github.com/labeveryday/nba_mcp_server.git
cd nba_mcp_server
uv sync

使用 pip

pip install nba-stats-mcp

从源码安装

git clone https://github.com/labeveryday/nba_mcp_server.git
cd nba_mcp_server
python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
pip install -e .

其他 MCP 客户端的使用方法

Python/Strands

from mcp import stdio_client, StdioServerParameters
from strands.tools.mcp import MCPClient

mcp_client = MCPClient(lambda: stdio_client(
    StdioServerParameters(
        command="uvx",
        args=["nba-stats-mcp"]
    )
))

单独运行（用于测试）

# 如果是通过 pip/uvx 安装的
nba-stats-mcp

# 或者从源码
uv run nba-stats-mcp
# 或者
python -m nba_mcp_server

配置

日志级别

通过环境变量 NBA_MCP_LOG_LEVEL 控制日志的详细程度（默认：WARNING）：

export NBA_MCP_LOG_LEVEL=INFO  # 用于调试
nba-stats-mcp

在 Claude Desktop 配置中：

{
  "mcpServers": {
    "nba-stats": {
      "command": "uvx",
      "args": ["nba-stats-mcp"],
      "env": {
        "NBA_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

数据来源

此服务器使用官方NBA API：

• 实时数据API - 实时得分和比赛数据
• 统计API - 球员统计、球队信息、历史数据
• 赛程API - 整个赛季赛程，包括未来比赛

开发

运行测试

uv sync --all-extras
uv run pytest
uv run pytest --cov=nba_mcp_server --cov-report=html

代码质量

uv run ruff check src/
uv run ruff format src/

要求

• Python 3.10+
• mcp >= 1.0.0
• httpx >= 0.27.0

许可证

MIT 许可证 - 查看 LICENSE 文件以获取详情。

贡献

欢迎贡献！请提交一个拉取请求。

关于作者

该项目由 Du'An Lightfoot 创建，他是一位热衷于AI代理、云基础设施和公共教学的开发者。

更多信息和联系方式：

• 🌐 网站: duanlightfoot.com
• 📺 YouTube: @LabEveryday
• 🐙 GitHub: @labeveryday