# AltSportsData MCP Server

MCP-compatible server that gives AI agents access to alternative sports data across 30+ leagues — odds, events, probabilities, settlement, and futures for prediction markets, DFS platforms, and sportsbooks.

## Quick Start

```bash
# Install
cd apps/altsportsdata-mcp
uv pip install -e ../altsportsdata-sdk
uv pip install -e .

# Run (stdio)
ALTSPORTSDATA_API_KEY=your_key altsportsdata-mcp

# Run (HTTP/SSE)
ALTSPORTSDATA_API_KEY=your_key altsportsdata-mcp --sse --port 8080
```

## Connect to Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "altsportsdata": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/altsportsdata-mcp",
        "python",
        "-m",
        "altsportsdata_mcp.server"
      ],
      "env": {
        "ALTSPORTSDATA_API_KEY": "your_api_key"
      }
    }
  }
}
```

Restart Claude Desktop. The 29 tools will appear in the tool picker (🔧 icon).

## Connect to Claude Code (CLI)

Claude Code discovers MCP servers from `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "altsportsdata": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/altsportsdata-mcp",
        "python",
        "-m",
        "altsportsdata_mcp.server"
      ],
      "env": {
        "ALTSPORTSDATA_API_KEY": "your_api_key"
      }
    }
  }
}
```

Or register globally:

```bash
claude mcp add altsportsdata \
  --command "uv" \
  --args "run" "--directory" "/path/to/altsportsdata-mcp" "python" "-m" "altsportsdata_mcp.server" \
  --env ALTSPORTSDATA_API_KEY=your_api_key
```

Verify with:

```bash
claude mcp list
```

## Connect to Cursor

Cursor supports MCP servers via its settings. Two options:

### Option A: Project-level (`.cursor/mcp.json`)

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "altsportsdata": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/altsportsdata-mcp",
        "python",
        "-m",
        "altsportsdata_mcp.server"
      ],
      "env": {
        "ALTSPORTSDATA_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Option B: Global (Cursor Settings)

1. Open Cursor → **Settings** → **MCP**
2. Click **Add new MCP server**
3. Enter:
   - **Name:** `altsportsdata`
   - **Command:** `uv run --directory /path/to/altsportsdata-mcp python -m altsportsdata_mcp.server`
4. Add environment variable `ALTSPORTSDATA_API_KEY`

### Option C: SSE/HTTP (Remote)

Run the server with HTTP transport:

```bash
ALTSPORTSDATA_API_KEY=your_key altsportsdata-mcp --sse --port 8080
```

Then in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "altsportsdata": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

This also works for any MCP client that supports HTTP/SSE transport (Windsurf, Continue, etc.).

## Connect to OpenClaw

Add to your OpenClaw config (`openclaw config edit`):

```yaml
mcp:
  servers:
    altsportsdata:
      command: uv
      args:
        - run
        - --directory
        - /path/to/altsportsdata-mcp
        - python
        - -m
        - altsportsdata_mcp.server
      env:
        ALTSPORTSDATA_API_KEY: your_api_key
```

## Installation via npm/PyPI (coming soon)

```bash
# When published to PyPI
pip install altsportsdata-mcp

# When published to npm (npx wrapper)
npx altsportsdata-mcp
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ALTSPORTSDATA_API_KEY` | Yes | Your AltSportsData API key |
| `ALTSPORTSDATA_BASE_URL` | No | Override API base URL |
| `ODDS_FORMAT` | No | Default odds format: `american` (default), `decimal`, `probability` |

## Tools (29)

### Discovery

| Tool | Description |
|------|-------------|
| `list_leagues` | List all 27+ alternative sports leagues with archetypes and markets |
| `get_league_info` | Detailed league info — archetype, data shape, contract hints, market menu |
| `get_market_catalog` | Browse market types by league or archetype |

### Events

| Tool | Description |
|------|-------------|
| `get_events` | List events with filters (league, status, date range, sort) |
| `get_event` | Single event details |
| `get_event_summary` | Comprehensive event summary with participants and market overview |
| `get_participants` | Competitors/athletes for an event |

### Odds & Markets

| Tool | Description |
|------|-------------|
| `get_odds` | Get odds for any market type (17 types supported) |
| `get_all_markets` | All available markets for an event in one call |
| `get_moneylines` | Winner/moneyline odds |
| `get_matchups` | Head-to-head matchup odds |
| `get_totals` | Over/under totals |
| `get_player_props` | Player prop bets |
| `get_exactas` | Exacta combinations (2, 3, or 4 way) |
| `get_podiums` | Podium finish odds |
| `get_heat_winners` | Heat/round winner odds |
| `get_fastest_lap` | Fastest lap odds (racing) |

### Analytics & Probabilities

| Tool | Description |
|------|-------------|
| `get_market_probabilities` | Implied win probabilities (vig-removed) |
| `get_fair_probabilities` | Fair probabilities for any market type |
| `get_favorites` | Top N favorites by odds |
| `calculate_sgp` | Same Game Parlay probability calculator |
| `convert_odds` | Convert between American, decimal, and probability formats |

### Settlement & Results

| Tool | Description |
|------|-------------|
| `get_settlement` | Settlement/grading data for completed events |
| `get_settled_results` | Final results and standings |

### Futures

| Tool | Description |
|------|-------------|
| `list_futures` | Available futures markets |
| `get_futures_odds` | Season futures odds (winner, top 2/3/5/10) |

### Specialty

| Tool | Description |
|------|-------------|
| `get_jaialai_matches` | Jai Alai match and set details |
| `get_jaialai_odds` | Jai Alai odds |
| `get_heat_scores` | Scores/lap times for a specific heat or round |

## MCP Resources

Static resources for context injection:

| URI | Description |
|-----|-------------|
| `altsportsdata://leagues` | All leagues with metadata |
| `altsportsdata://leagues/{code}` | Single league details |
| `altsportsdata://catalog` | Full market catalog |

## Supported Leagues

27+ alternative sports including:

| Category | Leagues |
|----------|---------|
| **Surf/Skate** | WSL (Surfing), SLS (Skateboarding) |
| **Racing** | F1, MotoGP, Supercross, Nitrocross, NHRA, Formula Drift, MotoAmerica, USAC, High Limit Racing, World Outlaws, Super Motocross |
| **Combat** | BKFC, Power Slap, BYB Extreme, LUX Fight League, Real American Freestyle |
| **Team** | MASL (Arena Soccer), NLL (Lacrosse), Athletes Unlimited, Goal Soccer |
| **Precision** | Disc Golf (DGPT), World Jai Alai |
| **Multi** | X Games, Major League Table Tennis |

## API Reference

This MCP server wraps the [AltSportsData Public API](https://api.altsportsdata.com/public/docs/).

- **Swagger/OpenAPI:** https://api.altsportsdata.com/public/docs/swagger
- **Documentation:** https://api.altsportsdata.com/public/docs/

## License

MIT