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]"

python -m nba_mcp.nba_server --mode claude

python -m nba_mcp.nba_server --mode local

{
  "mcpServers": {
    "nba": {
      "command": "python",
      "args": ["-m", "nba_mcp.nba_server", "--mode", "claude"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\nba_mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "nba": {
      "url": "http://localhost:8000"
    }
  }
}

# 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

# Get today's live scores
get_live_scores()

# Get scores for a specific date
get_live_scores(target_date="2024-03-15")

# Get player career stats
get_player_career_information(player_name="LeBron James", seasons=[2023])

# Get league leaders in points
get_league_leaders_info(stat_category="PTS", per_mode="PerGame", season="2023-24")

# Compare two players
compare_players(
    player1_name="Stephen Curry",
    player2_name="Damian Lillard",
    stat_categories=["PTS", "AST", "FG3M"]
)

# Cross-era comparison with adjustments
compare_players_era_adjusted(
    player1_name="Michael Jordan",
    player2_name="LeBron James"
)

# Get shot chart with hexagonal aggregation
get_shot_chart(
    player_or_team_name="Kevin Durant",
    season="2023-24",
    granularity="hexbin"
)

# Rich game context
get_game_context(
    team1_name="Lakers",
    team2_name="Warriors",
    season="2023-24"
)

# These all work with answer_nba_question()
"Who leads the NBA in assists this season?"
"Compare LeBron James and Michael Jordan career stats"
"What are the Lakers standings?"
"Show me Stephen Curry's shooting stats"
"Who scored the most points last night?"

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_mcp/
isort nba_mcp/

# Type checking
mypy nba_mcp/

# Linting
flake8 nba_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": []
}