# aria-mcp-football

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that tells you when your favourite football teams play and where to watch in Denmark. Built for [ARIA](https://github.com/kimhjort/aria) and shareable with the community.

Data from **[TheSportsDB.com](https://www.thesportsdb.com)**. No API key required for basic use — the free public dev key (`123`) is built in.

## Data Source

| Source | What | Attribution |
|---|---|---|
| [TheSportsDB](https://www.thesportsdb.com) | Fixtures, results | Data from TheSportsDB.com |

**Danish broadcast information** is a best-effort hint built into this server. TheSportsDB does not provide broadcaster data — the hints are researched defaults for the 2025/26 season. **Rights change. Always verify at [tvsporten.dk](https://tvsporten.dk) or [tvbolden.dk](https://tvbolden.dk).**

## Install & Run

```bash
npx aria-mcp-football
```

Or install globally:

```bash
npm install -g aria-mcp-football
aria-mcp-football
```

No API key required. Optionally set `THESPORTSDB_KEY` for a premium key.

Requires Node.js 20 or later.

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `THESPORTSDB_KEY` | No | TheSportsDB API key. Defaults to `"123"` (public free dev key). Set your own or a premium key if needed. |
| `FOLLOW_TEAMS` | No | Comma-separated TheSportsDB team IDs to follow (default: `133906,133899,133610` — Denmark, AGF, Chelsea). |
| `BROADCAST_MAP_JSON` | No | JSON object overriding the Danish broadcast hint map (keys: competition name pattern, values: broadcaster string). |

## Default Followed Teams

| Team | TheSportsDB ID | Competition |
|---|---|---|
| Denmark (national men's) | 133906 | UEFA Nations League, Friendlies, qualifiers |
| AGF Aarhus | 133899 | Danish Superliga |
| Chelsea | 133610 | Premier League |

Override via `FOLLOW_TEAMS=133906,133899,133610` (or any other TheSportsDB team IDs).

## Tools

### `get_my_fixtures`

Get upcoming fixtures for all followed teams within the next N days. This is the primary tool for ARIA's daily check.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `days` | number | No | Days ahead to look (default 14, max 60). |

**Returns:**

```json
{
  "followedTeams": ["Denmark (id:133906)", "AGF (id:133899)", "Chelsea (id:133610)"],
  "daysAhead": 14,
  "count": 2,
  "fixtures": [
    {
      "team": "AGF Aarhus",
      "opponent": "Viborg",
      "homeAway": "home",
      "competition": "Danish Superliga",
      "kickoffUtc": "2026-06-27T19:00:00.000Z",
      "kickoffLocal": "2026-06-27T21:00:00",
      "venue": "Ceres Park",
      "status": "Not Started",
      "danishBroadcast": "TV 2 Play / Viaplay"
    }
  ],
  "broadcastNote": "danishBroadcast is a best-effort hint. Rights change — verify at tvsporten.dk / tvbolden.dk."
}
```

---

### `get_team_fixtures`

Get upcoming fixtures or recent results for any football team by name or TheSportsDB team ID.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `team` | string | **Yes** | Team name (e.g. `"Chelsea"`, `"AGF"`) or numeric TheSportsDB team ID. |
| `days` | number | No | Days ahead to look (default 14, max 60). Ignored when `last` is set. |
| `last` | number | No | Return the last N results instead of upcoming fixtures (max 20). |

---

### `get_results`

Get recent finished match results with scores for a followed team or all followed teams.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `team` | string | No | Team name or ID to filter. If omitted, returns results across all followed teams. |
| `last` | number | No | Number of recent results (default 5, max 20). |

**Returns:**

```json
{
  "count": 1,
  "results": [
    {
      "team": "Chelsea",
      "opponent": "Arsenal",
      "homeAway": "home",
      "competition": "Premier League",
      "kickoffUtc": "2025-08-10T14:00:00.000Z",
      "score": "2 - 1",
      "outcome": "W"
    }
  ]
}
```

---

### `live_now`

Check if any followed team is currently playing. Live scores require a premium TheSportsDB key. On the free key (`123`) this returns a structured unavailable notice:

```json
{
  "status": "unavailable",
  "message": "Live-resultater kræver en premium TheSportsDB-nøgle."
}
```

**Parameters:** None

---

## Danish Broadcast Hints (2025/26 defaults)

| Competition (substring match) | Danish Broadcaster |
|---|---|
| Premier League | Viaplay (1 kamp/uge på Amazon Prime Video) |
| Superliga / Superligaen | TV 2 Play / Viaplay |
| UEFA Champions League | Viaplay |
| Friendlies (national) | TV 2 / TV 2 Play |
| UEFA Nations League | TV 2 / TV 2 Play |
| World Cup Qualification | TV 2 / TV 2 Play |
| Euro Qualification | TV 2 / TV 2 Play |
| Anything else | Ukendt — tjek tvsporten.dk / tvbolden.dk |

Override the entire map via `BROADCAST_MAP_JSON='{"premier league":"MyTV"}'`.

**These are best-effort hints. Rights change. Always verify at [tvsporten.dk](https://tvsporten.dk) or [tvbolden.dk](https://tvbolden.dk).**

## ARIA MCP Config

Add to your ARIA credentials / MCP config to use with ARIA:

```json
{
  "Name": "Football",
  "Command": "npx",
  "Args": ["-y", "aria-mcp-football"],
  "Env": {}
}
```

No key is required. If you have a premium TheSportsDB key you can optionally add:

```json
{
  "Name": "Football",
  "Command": "npx",
  "Args": ["-y", "aria-mcp-football"],
  "Env": {
    "THESPORTSDB_KEY": "your_premium_key_here"
  }
}
```

Note: `THESPORTSDB_KEY` is **not** a secret — the default (`123`) is a public free key. Only use `secret:` prefix in ARIA if you want to protect a personal premium key.

## Development

```bash
git clone https://github.com/kimhjort/aria-mcp-football
cd aria-mcp-football
npm install
npm run build
npm test
```

Run the server:

```bash
node dist/index.js
```

## License

MIT — see [LICENSE](LICENSE).

Data from [TheSportsDB.com](https://www.thesportsdb.com).