nba-stats-predictor-mcp

davorpavlov/nba-stats-predictor-mcp

3.1

If you are the rightful owner of nba-stats-predictor-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

An MCP-powered tool for the NBA stats predictor app that generates player performance forecasts using real-time data analysis and advanced statistical modeling.

MCP Server for NBA Stats Predictor Application

An MCP-powered tool for the NBA stats predictor app that generates player performance forecasts using real-time data analysis and advanced statistical modeling.

Demo

Features

  • 🏀 Real-time NBA Stats: Fetches latest player and team data from NBA API
  • 🤖 ML Predictions: Uses XGBoost for accurate player performance predictions
  • 🚀 FastAPI Backend: High-performance REST API for predictions
  • 🔧 MCP Integration: Seamlessly works with Claude Desktop
  • 🐳 Docker Support: Easy deployment with Docker and Docker Compose
  • ☁️ Coolify Ready: Deploy to Coolify with one click

Deployment Options

🚀 Quick Deploy with Coolify (Recommended)

Deploy the API to Coolify for production use. See for detailed instructions.

Quick Start:

  1. Fork this repository
  2. Create new application in Coolify
  3. Select branch: claude/coolify-deployment-setup-011CUzUkEmzLLA9UDBDfbVhS (or main after merge)
  4. Dockerfile is at root level - Coolify will auto-detect it
  5. Deploy!

🐳 Docker Compose (Local Development)

# Clone and start
git clone <repository-url>
cd nba-stats-predictor-mcp
docker-compose up -d

# API will be available at http://localhost:8000

💻 Local Development Setup

Prerequisites

  • Python 3.8+
  • pip
  • Claude Desktop

Step-by-Step Setup

  1. Clone this repository onto your local device

  2. Navigate to the project directory:

    cd nba-stats-predictor-application

  3. Create a virtual environment:

    python3 -m venv venv

  4. Activate the virtual environment:

    source venv/bin/activate

  5. Install dependencies:

    pip install -r requirements.txt

  6. Download the necessary data:

    python3 data_pipeline/download_data.py

  7. Train the prediction model:

    python3 models/train_model.py

  8. Start the FastAPI server:

    uvicorn api.fastapi_server:app --reload

  9. Open a new terminal

  10. Return to the project directory

  11. Install UV package manager:

    curl -LsSf https://astral.sh/uv/install.sh | sh

  12. Restart the terminal in this directory

  13. Run the MCP server:

    uv run mcp_main.py

  14. Open another new terminal

  15. Configure Claude Desktop:

    code ~/Library/Application\ Support/Claude/claude_desktop_config.json

    Note: If the file doesn't exist, create it.

  16. Add the following configuration to claude_desktop_config.json:

    {
    "mcpServers": {
        "NBA-stats-predictor": {
            "command": "/PATH/TO/PROJECT/DIRECTORY/.venv/bin/uv",
            "args": [
                "--directory",
                "/PATH/TO/PROJECT/DIRECTORY/",
                "run",
                "mcp_main.py"
            ]
        }
    }
}

    Remember to replace /PATH/TO/PROJECT/DIRECTORY/ with the actual path to your project.

  17. You should now be able to use this MCP tool on Claude Desktop.

Configuration

MCP Server Configuration

The MCP server can connect to either a local or remote API:

Local API (default):

{
    "mcpServers": {
        "NBA-stats-predictor": {
            "command": "/PATH/TO/PROJECT/.venv/bin/uv",
            "args": ["--directory", "/PATH/TO/PROJECT/", "run", "mcp_main.py"]
        }
    }
}

Remote API (Coolify deployment):

{
    "mcpServers": {
        "NBA-stats-predictor": {
            "command": "/PATH/TO/PROJECT/.venv/bin/uv",
            "args": ["--directory", "/PATH/TO/PROJECT/", "run", "mcp_main.py"],
            "env": {
                "NBA_API_URL": "https://your-coolify-domain.com"
            }
        }
    }
}

Environment Variables

Create a .env file in the project root (copy from .env.example):

# API URL for the MCP server to connect to
NBA_API_URL=http://localhost:8000  # or your Coolify URL

# For running the FastAPI server
PORT=8000

Usage

Once configured, you can use the NBA stats predictor tool in Claude Desktop:

Examples:

  • "Predict LeBron James stats against the Boston Celtics at home"
  • "What will Stephen Curry's performance be like against the Lakers away?"
  • "Show me predicted stats for Giannis Antetokounmpo vs the Warriors at home"

API Endpoints

The FastAPI server provides the following endpoints:

  • GET / - API information and available endpoints
  • GET /health - Health check endpoint
  • GET /docs - Interactive API documentation (Swagger UI)
  • POST /predict - Get player stat predictions

Example API Request:

curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "player_name": "LeBron James",
    "opponent_team": "BOS",
    "home_or_away": "Home"
  }'

Architecture

┌─────────────────┐      ┌──────────────┐      ┌─────────────────┐
│  Claude Desktop │ ───> │  MCP Server  │ ───> │  FastAPI Server │
│                 │      │  (mcp_main.py)│      │  (Port 8000)    │
└─────────────────┘      └──────────────┘      └─────────────────┘
                                                          │
                                                          v
                                                 ┌─────────────────┐
                                                 │   SQLite DB +   │
                                                 │   ML Model      │
                                                 └─────────────────┘

Troubleshooting

Local Development

  • Make sure all paths in the configuration are correct
  • Ensure the virtual environment is activated before running commands
  • Check that all dependencies are properly installed
  • Verify that the FastAPI server is running before using the MCP tool

Docker/Coolify Deployment

  • Check application logs in Coolify dashboard
  • Verify environment variables are correctly set
  • Ensure PORT is set to 8000
  • If database/model is missing, run initialization scripts manually
  • For SSL issues, verify domain configuration in Coolify

MCP Connection Issues

  • Restart Claude Desktop after configuration changes
  • Check that NBA_API_URL is correctly set
  • Verify the API is accessible from your machine
  • Look for errors in Claude Desktop logs

Development

Project Structure

nba-stats-predictor-mcp/
├── mcp_main.py                          # MCP server implementation
├── pyproject.toml                       # MCP dependencies
├── docker-compose.yml                   # Local development setup
├── .env.example                         # Environment configuration template
├── COOLIFY_DEPLOYMENT.md               # Coolify deployment guide
└── nba-stats-predictor-application/    # FastAPI application (submodule)
    ├── Dockerfile                       # Container configuration
    ├── api/
    │   └── fastapi_server.py           # FastAPI endpoints
    ├── models/
    │   ├── predict.py                  # Prediction logic
    │   └── train_model.py              # Model training
    └── data_pipeline/
        ├── download_data.py            # NBA data fetching
        └── database.py                 # Database management

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test locally with Docker Compose
  5. Submit a pull request

License

[Add your license here]

Credits

Built with: