NBA数据访问服务器

┌─────────────────────────────────────────────────────────────────┐
│                        NBA MCP Server                           │
│                                                                 │
│  Claude Desktop  ←→  MCP Protocol  ←→  Unified Fetch System    │
│  VS Code/Cursor  ←→  FastMCP      ←→  NBA API Client           │
│  Custom Client   ←→  HTTP/Stdio   ←→  Redis Cache + Filters   │
│                                                                 │
│  📊 50+ Endpoints  │  🔍 Fuzzy Matching  │  ⚡ Sub-ms Cache    │
│  🎯 Smart Filters  │  🔗 Batch Queries   │  📈 Metrics/Tracing │
└─────────────────────────────────────────────────────────────────┘

# Install via pipx (recommended) or pip
pipx install nba-mcp
# OR: pip install nba-mcp

# Start the server
nba-mcp serve --mode claude

# In another terminal, try fetching data
nba-mcp fetch league_leaders --params stat_category=PTS season=2024-25 --filter "PTS >= 25"

# Browse available endpoints
nba-mcp catalog

# Show configuration
nba-mcp config

# Clone and start with docker-compose
git clone https://github.com/ghadfield32/nba_mcp.git
cd nba_mcp
docker-compose up -d

# The server is now running with Redis caching at http://localhost:8000

git clone https://github.com/ghadfield32/nba_mcp.git
cd nba_mcp

# Using UV (recommended)
pip install uv
uv venv nbavenv

# Activate on Windows
.\nbavenv\Scripts\activate

# Activate on Unix/MacOS
source nbavenv/bin/activate

# Using uv (resolves deps from pyproject.toml / uv.lock)
uv sync --extra dev

# Or use pip directly (editable install with dev extras)
pip install -e ".[dev]"

# Copy example env file and customize
cp .env.example .env
# Edit .env with your preferred settings

# Start server with CLI
nba-mcp serve --mode claude

# Or with custom port
nba-mcp serve --mode local --port 8005

# Claude Desktop Mode (Port 8000)
python -m nba_mcp.nba_server --mode claude

# Local LLM Mode (Port 8001)
python -m nba_mcp.nba_server --mode local

# Basic deployment with Redis
docker-compose up -d

# With monitoring (Prometheus + Grafana)
docker-compose --profile monitoring up -d

from nba_api_mcp.data.unified_fetch import unified_fetch
import asyncio

# Simple fetch - get player career stats
async def get_lebron_stats():
    result = await unified_fetch(
        endpoint="player_career_stats",
        params={"player_name": "LeBron James"}
    )

    print(f"Fetched {result.data.num_rows} rows")
    print(f"Execution time: {result.execution_time_ms:.2f}ms")
    print(f"From cache: {result.from_cache}")

    # Access the data as PyArrow Table
    data = result.data

    # Or convert to tuple format
    data, provenance = result.to_tuple()

asyncio.run(get_lebron_stats())

# Filter team game log for wins with 110+ points
result = await unified_fetch(
    endpoint="team_game_log",
    params={"team": "Lakers", "season": "2023-24"},
    filters={
        "WL": ["==", "W"],           # Only wins
        "PTS": [">=", 110],          # Scored 110+ points
        "FG_PCT": [">", 0.5]         # Shooting over 50%
    }
)

# Use IN operator for multiple values
result = await unified_fetch(
    endpoint="team_standings",
    params={"season": "2023-24"},
    filters={
        "team_abbreviation": ["IN", ["LAL", "GSW", "BOS"]]
    }
)

# Use BETWEEN for ranges
result = await unified_fetch(
    endpoint="player_game_logs",
    params={"player_name": "Stephen Curry", "season": "2023-24"},
    filters={
        "PTS": ["BETWEEN", [25, 40]],  # Scored between 25-40 points
        "FG3M": [">=", 5]               # Made 5+ threes
    }
)

from nba_api_mcp.data.unified_fetch import batch_fetch

# Fetch multiple datasets in parallel
results = await batch_fetch([
    {
        "endpoint": "player_career_stats",
        "params": {"player_name": "LeBron James"}
    },
    {
        "endpoint": "player_career_stats",
        "params": {"player_name": "Stephen Curry"}
    },
    {
        "endpoint": "team_standings",
        "params": {"season": "2023-24"}
    },
    {
        "endpoint": "league_leaders",
        "params": {"stat_category": "PTS"},
        "filters": {"PTS": [">=", 25]}
    }
])

# Process results
for i, result in enumerate(results):
    print(f"Query {i+1}: {result.data.num_rows} rows in {result.execution_time_ms:.2f}ms")

result = await unified_fetch(
    endpoint="player_career_stats",
    params={"player_name": "LeBron James"}
)

# Access the data (PyArrow Table)
data = result.data
print(f"Rows: {data.num_rows}")
print(f"Columns: {data.num_columns}")

# Performance metrics
print(f"Execution time: {result.execution_time_ms:.2f}ms")
print(f"From cache: {result.from_cache}")

# Provenance tracking
print(f"Source endpoints: {result.provenance.source_endpoints}")
print(f"Operations: {result.provenance.operations}")
print(f"Parameters: {result.provenance.parameters}")

# Warnings and transformations
if result.warnings:
    print(f"Warnings: {result.warnings}")
if result.transformations:
    print(f"Transformations: {result.transformations}")

# Convert to pandas DataFrame
df = data.to_pandas()

# Or get as tuple for backward compatibility
data, provenance = result.to_tuple()

# This filter will be pushed to the API level (faster)
result = await unified_fetch(
    endpoint="player_game_logs",
    params={"player_name": "Stephen Curry"},
    filters={
        "date_from": [">=", "2024-01-01"],  # ✅ Pushed to API
        "date_to": ["<=", "2024-03-01"]     # ✅ Pushed to API
    }
)

# These filters are applied post-fetch using DuckDB (still fast)
result = await unified_fetch(
    endpoint="player_game_logs",
    params={"player_name": "Stephen Curry"},
    filters={
        "PTS": [">=", 30],              # Applied post-fetch
        "FG3M": [">=", 5],              # Applied post-fetch
        "PLUS_MINUS": [">", 10]         # Applied post-fetch
    }
)

print(result.transformations)
# Output: ['Pushed 2 filter(s) to API: [\'date_from\', \'date_to\']']

# Use cache (default)
result = await unified_fetch(
    endpoint="player_career_stats",
    params={"player_name": "LeBron James"},
    use_cache=True
)

# Disable cache for this request
result = await unified_fetch(
    endpoint="live_scoreboard",
    params={"target_date": "2024-03-15"},
    use_cache=False
)

# Force refresh even if cached
result = await unified_fetch(
    endpoint="team_standings",
    params={"season": "2023-24"},
    force_refresh=True
)

# Server configuration
export NBA_MCP_PORT=8000
export NBA_MCP_LOG_LEVEL=INFO

# Redis caching (optional)
export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_DB=0
export ENABLE_REDIS_CACHE=true

# Rate limiting
export NBA_MCP_DAILY_QUOTA=10000
export NBA_MCP_SIMPLE_RATE_LIMIT=60
export NBA_MCP_COMPLEX_RATE_LIMIT=30

# Observability (optional)
export ENABLE_METRICS=true
export ENABLE_TRACING=false
export OTLP_ENDPOINT=http://localhost:4317

You: "What are the current NBA standings for the Western Conference?"

Claude: [Uses get_team_standings tool to fetch data]
Here are the current Western Conference standings...

You: "Show me LeBron James' stats from last season"

Claude: [Uses get_player_career_information tool]
LeBron James' 2023-24 season statistics:
- Games: 71
- PPG: 25.7
- RPG: 7.3
- APG: 8.3
...

You: What games are on today?

Claude: [Calls get_live_scores()]
Today's NBA games:
1. Lakers vs Warriors (7:30 PM PT) - Live: GSW 98, LAL 95 (Q3)
2. Celtics vs Heat (7:00 PM ET) - Final: BOS 112, MIA 103
3. Nuggets vs Suns (8:00 PM MT) - Upcoming

You: Show me Giannis Antetokounmpo's stats this season

Claude: [Calls get_player_career_information(player_name="Giannis Antetokounmpo", seasons=["2024-25"])]
Giannis Antetokounmpo 2024-25 Season:
- Games Played: 45
- PPG: 30.8
- RPG: 11.2
- APG: 6.1
- FG%: 61.2%
- Advanced: 65.3 TS%, 34.2 USG%, 28.5 PER

You: What are the current Western Conference standings?

Claude: [Calls get_team_standings(season="2024-25", conference="West")]
Western Conference Standings:
1. Thunder (35-8) - 81.4%
2. Nuggets (32-11) - 74.4%
3. Grizzlies (31-12) - 72.1%
...

You: Compare Luka Doncic and Shai Gilgeous-Alexander this season

Claude: [Calls compare_players(player1_name="Luka Doncic", player2_name="Shai Gilgeous-Alexander", stat_categories=["PTS", "AST", "REB"])]

Luka Doncic vs Shai Gilgeous-Alexander (2024-25):

Points per game:
- Luka: 28.9
- SGA: 30.3 ✓

Assists per game:
- Luka: 8.2 ✓
- SGA: 5.6

Rebounds per game:
- Luka: 8.3 ✓
- SGA: 5.7

from nba_api_mcp.nba_server import mcp

# Example: Call a tool directly
result = await mcp.call_tool(
    "get_player_career_information",
    {
        "player_name": "LeBron James",
        "seasons": ["2023-24"]
    }
)

ollama pull llama3.2:3b

python -m nba_mcp.nba_server --mode local

python examples/langgraph_ollama_agent_w_tools.py --mode local

Enter a question:
> who leads the nba in assists this season?

AIMessage: Let me check the league leaders for assists this season.
ToolMessage: [League leaders data for assists...]
AIMessage: Based on the data, Tyrese Haliburton leads the NBA in assists...

# Run all tests
pytest tests/

# Run specific test categories
pytest tests/test_api_client.py
pytest tests/api/test_live_scores.py
pytest tests/api/test_player_stats.py

# Run integration tests
pytest tests/integration/

# Run with coverage
pytest --cov=nba_mcp --cov-report=html tests/

python run_validation.py

# Format code
black nba_api_mcp/
isort nba_api_mcp/

# Type checking
mypy nba_api_mcp/

# Linting
flake8 nba_api_mcp/

http://localhost:8000/metrics

# Start Grafana (with Docker)
cd grafana
docker-compose up -d

# Access at http://localhost:3000
# Default credentials: admin/admin

# Ensure PYTHONPATH is set correctly
export PYTHONPATH=/path/to/nba_mcp

# Or reinstall in development mode
pip install -e .

# Check rate limit status in logs
# Reduce request frequency
# Wait for quota reset (daily)

# Verify Redis is running
redis-cli ping

# Or disable Redis caching
export ENABLE_REDIS_CACHE=false

# The NBA API can be flaky
# The server includes automatic retries with exponential backoff
# Check logs for specific error details

export NBA_MCP_LOG_LEVEL=DEBUG
python -m nba_mcp.nba_server --mode claude

# Check Python version
python --version  # Should be 3.10+

# Verify dependencies
pip list | grep nba_api
pip list | grep fastmcp

# Test API connectivity
python -c "from nba_api.stats.static import players; print(len(players.get_players()))"

NBA MCP Server
├── nba_server.py           # Main FastMCP server
├── api/                    # Core API layer
│   ├── client.py           # NBA API client
│   ├── advanced_stats.py   # Advanced statistics
│   ├── entity_resolver.py  # Fuzzy entity matching
│   ├── shot_charts.py      # Shot chart data
│   ├── game_context.py     # Multi-source composition
│   ├── era_adjusted.py     # Cross-era adjustments
│   └── tools/              # API utilities
├── nlq/                    # Natural language processing
│   ├── parser.py           # Query parsing
│   ├── planner.py          # Query planning
│   ├── executor.py         # Parallel execution
│   └── synthesizer.py      # Response formatting
├── cache/                  # Redis caching layer
├── rate_limit/             # Token bucket rate limiting
├── observability/          # Metrics and tracing
└── schemas/                # Pydantic models and schemas

{
  "status": "success",
  "data": { ... },
  "metadata": {
    "version": "v1",
    "schema_version": "2025-01",
    "timestamp": "2024-03-15T10:30:00Z",
    "source": "nba_api",
    "cached": true,
    "cache_ttl": 3600
  },
  "errors": []
}

# Install dependencies
uv sync --extra dev
# or
pip install -e ".[dev]"

# Start server for Claude Desktop
python -m nba_api_mcp.nba_server --mode claude

# Start server for local LLMs
python -m nba_api_mcp.nba_server --mode local

# Run tests
pytest tests/

# Run validation
python run_validation.py

# Format code
black nba_api_mcp/ && isort nba_api_mcp/

from nba_api_mcp.data.unified_fetch import unified_fetch, batch_fetch

# Basic fetch
result = await unified_fetch("player_career_stats", {"player_name": "LeBron James"})

# With filters
result = await unified_fetch(
    "team_game_log",
    {"team": "Lakers", "season": "2023-24"},
    filters={"WL": ["==", "W"], "PTS": [">=", 110]}
)

# Batch fetch
results = await batch_fetch([
    {"endpoint": "player_career_stats", "params": {"player_name": "LeBron"}},
    {"endpoint": "team_standings", "params": {"season": "2023-24"}},
])

# Cache control
result = await unified_fetch(..., use_cache=False)  # Disable cache
result = await unified_fetch(..., force_refresh=True)  # Force refresh

# Equality
{"WL": ["==", "W"]}               # Equal to
{"conference": ["!=", "East"]}    # Not equal to

# Comparison
{"PTS": [">", 20]}                # Greater than
{"PTS": [">=", 20]}               # Greater than or equal
{"TOV": ["<", 3]}                 # Less than
{"TOV": ["<=", 3]}                # Less than or equal

# Lists and Patterns
{"TEAM": ["IN", ["LAL", "GSW"]]}  # In list
{"PTS": ["BETWEEN", [20, 30]]}    # Between values
{"PLAYER_NAME": ["LIKE", "%James%"]}  # Pattern match

# Player Data
"player_career_stats"       # Career statistics
"player_game_logs"          # Game-by-game logs
"player_advanced_stats"     # Advanced metrics

# Team Data
"team_standings"            # Standings
"team_game_log"            # Game history
"team_advanced_stats"      # Team efficiency

# League Data
"league_leaders"           # League leaders
"league_game_log"          # All games

# Game Data
"live_scoreboard"          # Live scores
"play_by_play"             # Play-by-play
"box_score"                # Box scores

# Claude Desktop Config
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json

# VS Code / Cursor MCP Config
Windows: %APPDATA%\Code\User\mcp.json
         %APPDATA%\Cursor\User\mcp.json
macOS:   ~/.config/Code/User/mcp.json
         ~/.config/Cursor/User/mcp.json

# Essential
NBA_MCP_PORT=8000
NBA_MCP_LOG_LEVEL=INFO

# Redis Cache
REDIS_HOST=localhost
REDIS_PORT=6379
ENABLE_REDIS_CACHE=true

# Rate Limits
NBA_MCP_DAILY_QUOTA=10000
NBA_MCP_SIMPLE_RATE_LIMIT=60
NBA_MCP_COMPLEX_RATE_LIMIT=30

# Observability
ENABLE_METRICS=true
ENABLE_TRACING=false

# Module not found
export PYTHONPATH=/path/to/nba_api_mcp
pip install -e .

# Redis connection issues
redis-cli ping  # Check if Redis is running
export ENABLE_REDIS_CACHE=false  # Or disable Redis

# Check Python version
python --version  # Must be 3.10+

# Verify installation
python -c "from nba_api.stats.static import players; print(len(players.get_players()))"