# @kickoffapi/mcp

Official Model Context Protocol (MCP) server for **KickoffAPI** — the low-latency, real-time football data API.

Connect AI assistants (Claude Desktop, Cursor, Claude Code, Antigravity, and custom agent frameworks) directly to live football scores, fixtures, lineups, xG projections, Monte Carlo simulations, bookmaker odds, and player/team statistics.

---

## ⚡ Quick Start

### 1. Claude Desktop Setup

Add the following to your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "kickoffapi": {
      "command": "npx",
      "args": ["-y", "@kickoffapi/mcp"],
      "env": {
        "KICKOFFAPI_KEY": "YOUR_KICKOFFAPI_KEY_HERE"
      }
    }
  }
}
```

Restart Claude Desktop. The hammer icon in Claude will now show all KickoffAPI tools!

---

### 2. Cursor IDE Setup

In your project root, create or edit `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kickoffapi": {
      "command": "npx",
      "args": ["-y", "@kickoffapi/mcp"],
      "env": {
        "KICKOFFAPI_KEY": "YOUR_KICKOFFAPI_KEY_HERE"
      }
    }
  }
}
```

---

### 3. Remote / Hosted SSE Agent Setup

If you prefer connecting your agent to our hosted cloud MCP server over Server-Sent Events (SSE) without running a local process:

- **SSE Endpoint**: `https://api.kickoffapi.com/mcp/sse?key=YOUR_KICKOFFAPI_KEY`
- **JSON-RPC Post**: `https://api.kickoffapi.com/mcp`

For agents supporting remote SSE transports:

```json
{
  "mcpServers": {
    "kickoffapi-cloud": {
      "url": "https://api.kickoffapi.com/mcp/sse?key=YOUR_KICKOFFAPI_KEY"
    }
  }
}
```

---

## 🛠 Available Tools

| Tool | Description | Key Parameters |
| :--- | :--- | :--- |
| `get_live_scores` | Fetch real-time live match scores, minute, and scorelines | `league_id`, `timeframe` |
| `get_fixtures` | Scheduled fixtures by date or league with kick-off times | `date`, `league_id`, `status` |
| `get_fixture_details` | Full match stats, lineups, substitutions, cards, goals | `fixture_id` (required) |
| `get_standings` | League table ranking, points, GD, form guide | `league_id` (required), `season` |
| `get_projections` | Dixon-Coles xG, win/draw/loss %, scoreline matrix | `fixture_id` or `home_team_id`/`away_team_id` |
| `get_team_stats` | Team form, goals per game, clean sheets, records | `team_id` (required), `league_id` |
| `get_player_stats` | Goals, assists, shots, passing, cards, minutes | `player_id` (required), `team_id` |
| `get_odds` | 1X2, Over/Under, BTTS odds across top bookmakers | `fixture_id` (required), `market` |
| `search_teams_and_leagues` | Find team and league IDs by name or search phrase | `query` (required), `type` |
| `get_season_sim` | Monte Carlo season forecast, title & top-4 odds | `league_id` (required), `season` |
| `get_xg` | Gradient-boosted expected goals (xG) shot and match model | `distance`, `angle`, `body_part`, `situation` |
| `get_value_bets` | Positive Expected Value (+EV) market opportunities | `league_id`, `min_edge`, `limit` |
| `get_fixture_insights` | AI match simulations, form trajectories, and probabilities | `fixture_id` (required) |

---

## 🔐 Environment Variables

| Variable | Description | Default |
| :--- | :--- | :--- |
| `KICKOFFAPI_KEY` | Your KickoffAPI key (obtain from [kickoffapi.com/dashboard](https://kickoffapi.com/dashboard)) | *Required* |
| `KICKOFFAPI_BASE_URL` | API base endpoint | `https://api.kickoffapi.com` |

---

## 📖 License

MIT © [KickoffAPI](https://kickoffapi.com)