Content
# 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).
