AI导哈

NBA数据MCP服务

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

  • by labeveryday
  • Python
  • 混合部署
  • 11 星标
  • 更新于
在 GitHub 查看 labeveryday/nba_mcp_server

使用说明

🏀 NBA MCP服务器

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

一种模型上下文协议（MCP）服务器，提供对NBA实时和历史数据的访问，包括球员统计数据、比赛得分、球队信息和高级分析。 v0.3.0：所有21个工具都接受人名（而不仅仅是ID），返回结构化数据+压缩文本，并将默认季节设置为当前季节。针对大型和小型LLM客户进行了优化。

Claude Desktop快速入门

  1. 安装服务器：
# Using uvx (recommended - no install required)
uvx nba-stats-mcp

# Or using pip
pip install nba-stats-mcp

# Or from source
git clone https://github.com/labeveryday/nba-stats-mcp.git
cd nba-stats-mcp
uv sync
  1. 添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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-stats-mcp/",
        "run",
        "nba-stats-mcp"
      ]
    }
  }
}
  1. 重新启动克劳德桌面

你可以问什么

  • “给我看看今天的NBA比赛”
  • “勒布朗·詹姆斯本赛季的数据如何？”
  • “为湖人队对阵勇士队取得得分”
  • “谁是本赛季得分最高的10人？”
  • “向我展示历史助攻领先者”
  • “凯尔特人队下一场比赛是什么时候？”
  • “获取斯蒂芬·库里的投篮图表”
  • “偏转的联盟领袖是谁？”
  • “给我看看Giannis的职业奖”

可用工具（共21个）

所有工具均接受 人名 --不需要先解析ID。每个响应都包括结构化 data +紧凑型 text.

玩家工具

  • get_player_info(player) -玩家简介和详细信息（接受姓名或ID）
  • get_player_stats(player, stat_type) -赛季、职业生涯、比赛日志、冲刺、防守或高级统计数据
  • get_player_awards(player) -所有奖项和荣誉
  • get_shooting_data(player, data_type) -射击图表或射击分段

团队工具

  • get_team_roster(team) -球队名单（接受球队名称或ID）
  • get_team_advanced_stats(team) -团队效率指标（ORtg、DRtg、速度）
  • get_schedule(team) -即将到来的游戏
  • get_standings() -按会议划分的联赛排名

游戏工具

  • get_scoreboard(date?) -日期游戏（默认为今天）
  • find_game(team1, team2?, date?) -按团队匹配查找game_id
  • get_game_details(game_id) -包含球队统计数据的实时比赛信息
  • get_box_score(game_id) -带球员统计数据的全框得分
  • get_play_by_play(game_id) -使用时间戳逐个播放
  • get_game_rotation(game_id) -球员轮换/替换数据

联盟工具

  • get_leaders(category, scope) -当前赛季、历史或喧嚣的领导者
  • get_season_awards(season?) -赛季MVP和主要奖项

复合工具（v0.3.0中的新功能）

  • compare_players(player1, player2) -并排球员比较
  • daily_summary(date?) -约会的所有游戏+分数
  • team_overview(team) -名册+记录+即将到来的日程安排

分辨率工具

  • resolve_player_id(query) -将玩家姓名与ID进行模糊匹配
  • resolve_team_id(query) -模糊匹配球队名称到ID

视觉资产（公共NBA CDN）

此MCP服务器也返回 公共NBA CDN资产URL （没有API键）以及多个工具响应中的ID，因此UI客户端可以呈现视觉效果。

  • 球员头像:
    • 全尺寸： https://cdn.nba.com/headshots/nba/latest/1040x760/{playerId}.png
    • 缩略图： https://cdn.nba.com/headshots/nba/latest/260x190/{playerId}.png
  • 团队徽标（SVG）:
    • https://cdn.nba.com/logos/nba/{teamId}/global/L/logo.svg

包含这些URL的工具：

  • 玩家: resolve_player_id, get_player_info, get_player_stats
  • 团队: resolve_team_id, get_standings, get_team_roster

安装选项

紫外线（推荐）

git clone https://github.com/labeveryday/nba-stats-mcp.git
cd nba-stats-mcp
uv sync

使用pip

pip install nba-stats-mcp

来源

git clone https://github.com/labeveryday/nba-stats-mcp.git
cd nba-stats-mcp
python -m venv .venv
source .venv/bin/activate  # On 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"]
    )
))

独立运行（用于测试）

# If installed via pip/uvx (stdio, default)
nba-stats-mcp

# Or from source
uv run nba-stats-mcp
# or
python -m nba_mcp_server

流式HTTP传输（v0.2.0中的新功能）

# Run as an HTTP server instead of stdio
nba-stats-mcp --transport streamable-http --host 127.0.0.1 --port 8000

# Also supports SSE transport
nba-stats-mcp --transport sse --port 8000

MCP检查员

npx @modelcontextprotocol/inspector
# In the Inspector UI, configure a stdio server:
# - Command: uv
# - Args: --directory /absolute/path/to/nba-stats-mcp run nba-stats-mcp
#   (or Command: python, Args: -m nba_mcp_server)

JSON响应格式（v3.0）

所有工具返回a 单个JSON对象 （编码为MCP TextContent.text 字符串）。顶级架构是：

  • tool_name：运行的工具
  • arguments：已传递参数
  • text：简洁的1-3行摘要（干净--没有ID或CDN URL）
  • data：具有所有机器可读值的结构化字典（用于编程的主要输出）
  • entities：提取的ID+用于UI渲染的资源URL

视觉资产（公共NBA CDN）

服务器在中包含公共CDN URL（不需要API密钥） entities:

  • 球员头像:
    • headshot_url: https://cdn.nba.com/headshots/nba/latest/1040x760/{playerId}.png
    • thumbnail_url: https://cdn.nba.com/headshots/nba/latest/260x190/{playerId}.png
  • 团队徽标:
    • team_logo_url: https://cdn.nba.com/logos/nba/{teamId}/global/L/logo.svg

配置

日志记录级别

使用控制日志的冗长程度 NBA_MCP_LOG_LEVEL 环境变量（默认值：警告）：

export NBA_MCP_LOG_LEVEL=INFO  # For debugging
nba-stats-mcp

在Claude桌面配置中：

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

性能和可靠性调整

您可以通过env-vars调整请求行为（当代理执行并行工具调用时很有帮助）：

  • NBA_MCP_HTTP_TIMEOUT_SECONDS：每次请求超时（默认值： 30)
  • NBA_MCP_MAX_CONCURRENCY：最大并发出站NBA API请求数（默认值： 8)
  • NBA_MCP_RETRIES：瞬态故障重试（429/5xx/网络）（默认值： 2)
  • NBA_MCP_CACHE_TTL_SECONDS：缓存统计端点的TTL（默认值： 120)
  • NBA_MCP_LIVE_CACHE_TTL_SECONDS：缓存活动端点的TTL（默认值： 5)
  • NBA_MCP_TLS_VERIFY：启用TLS验证（默认值： 1).如果你看到 PermissionError 读取CA包（在沙盒/MOS隐私上下文中很常见），设置为 0.

Claude桌面配置示例：

{
  "mcpServers": {
    "nba-stats": {
      "command": "uvx",
      "args": ["nba-stats-mcp"],
      "env": {
        "NBA_MCP_LOG_LEVEL": "INFO",
        "NBA_MCP_MAX_CONCURRENCY": "8",
        "NBA_MCP_CACHE_TTL_SECONDS": "120",
        "NBA_MCP_LIVE_CACHE_TTL_SECONDS": "5",
        "NBA_MCP_RETRIES": "2",
        "NBA_MCP_HTTP_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

数据源

此服务器使用官方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/

安全（土匪）

静态安全分析：

uv sync --all-extras
uv run bandit -c pyproject.toml -r src/

发布到PyPI

此项目使用Hatching进行构建。推荐的发布步骤：

# 1) Ensure clean env + tests
uv sync --all-extras
uv run pytest
uv run ruff check src/ tests/
uv run bandit -c pyproject.toml -r src/

# 2) Build distributions
uv run python -m build

# 3) Upload
uv run twine upload dist/*

提示：对于TestPyPI上传，请使用 twine upload --repository testpypi dist/*.

需求

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

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请提交拉取请求。

关于作者

该项目由以下人员创建 杜安轻脚，一位对人工智能代理、云基础设施和公共教学充满热情的开发人员。

了解更多信息并连接：

相关 MCP