# Quant-Sports MCP Server — Quick Start Guide

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Version](https://img.shields.io/badge/MCP-1.0.0-blue)](https://modelcontextprotocol.io)

**Quant-Sports MCP** is a high-performance Model Context Protocol (MCP) server that wraps the `quantitative_sports` quantitative sports betting toolkit. It provides AI agents with professional-grade tools for expected value (EV) calculation, Monte Carlo predictions, historical backtesting, and portfolio risk management.

## 🚀 Quick Start

### Installation
Ensure you have `uv` installed. Navigate to the project root and run:

```bash
uv sync
uv run quant-sports-mcp
```

### OpenCode Integration
Add the following to your `opencode.json` to enable the server with all categories:

```json
{
  "mcpServers": {
    "quantitative_sports": {
      "command": "uv",
      "args": ["run", "quant-sports-mcp"],
      "env": {
        "QUANT_SPORTS_BETTING_MATH": "true",
        "QUANT_SPORTS_BACKTESTING": "true",
        "QUANT_SPORTS_PREDICTIONS": "true",
        "QUANT_SPORTS_RATINGS": "true",
        "QUANT_SPORTS_DATA_SOURCES": "true",
        "QUANT_SPORTS_PORTFOLIO": "true",
        "QUANT_SPORTS_PARLAY": "true",
        "QUANT_SPORTS_ANALYSIS": "true"
      }
    }
  }
}
```

## ⚙️ Configuration Reference

The server uses a category-based toggle system. You can enable/disable groups of tools via environment variables or a JSON config file.

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `QUANT_SPORTS_BETTING_MATH` | `true` | EV, Kelly, Arbitrage, Odds conversion |
| `QUANT_SPORTS_BACKTESTING` | `true` | Historical simulation and performance metrics |
| `QUANT_SPORTS_PREDICTIONS` | `true` | PRA and Game-level XGBoost predictions |
| `QUANT_SPORTS_RATINGS` | `true` | RAPTOR, Massey, PageRank, and Bayesian priors |
| `QUANT_SPORTS_DATA_SOURCES` | `true` | Pinnacle and ESPN scrapers |
| `QUANT_SPORTS_PORTFOLIO` | `true` | Risk analysis, position sizing, and heat checks |
| `QUANT_SPORTS_PARLAY` | `true` | Correlated Monte Carlo parlay optimization |
| `QUANT_SPORTS_ANALYSIS` | `true` | Matchup, Venue, and Rest-day splits |
| `QUANT_SPORTS_MCP_CONFIG` | (none) | Path to a JSON config file for advanced overrides |
| `QUANT_SPORTS_MCP_LOG_LEVEL` | `INFO` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |

## 📚 Documentation

- **[TOOLS.md](./TOOLS.md)**: The comprehensive tool reference including parameter types, return formats, and mathematical formulas for all 37 tools.
- **[ARCHITECTURE.md](./ARCHITECTURE.md)**: Technical specification and implementation details.

## 🛠 Companion Servers

For a complete quantitative betting workflow, we recommend integrating Quant-Sports with:
- **Neuralgentics / memini-ai**: For long-term memory of strategy performance.
- **boomerang-v3**: To orchestrate complex "Research $\rightarrow$ Predict $\rightarrow$ Size $\rightarrow$ Deploy" workflows.
- **Calculator MCP**: For independent verification of complex math.
- **PostgreSQL MCP**: For direct access to the Quant-Sports data warehouse.

## 📄 License
MIT License. See LICENSE file for details.