# aria-mcp-tvguide-dk

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes the Danish TV guide (EPG) to AI assistants. Built for [ARIA](https://github.com/kimhjort/aria) and shareable with the community.

**Fully keyless** — no API key required.

## What it does

Lets your AI assistant answer questions like:

- *"Hvad går der i fjernsynet i aften?"*
- *"Hvad sender DR1 kl. 20?"*
- *"Hvornår sender TV 2 Klovn?"*
- *"Hvor kan jeg se VM-kampen i aften?"*

## Data Source

EPG data is provided by **[Allente Denmark](https://allente.dk)** via their internal EPG API (`https://cs-vcb.allente.dk/epg/events`). The data is best-effort for personal/hobby use. Check Allente's Terms of Service before any redistribution or commercial use.

Covers all major Danish channels: DR1, DR2, DR Ramasjang, TV 2, TV 2 News, TV 2 Charlie, TV 2 Sport, TV3, TV3+, Kanal 4, Kanal 5, 6'eren, CANAL9, dk4, Eurosport, Discovery, National Geographic, BBC Nordic, and more.

## Install & Run

```bash
npx aria-mcp-tvguide-dk
```

Or install globally:

```bash
npm install -g aria-mcp-tvguide-dk
aria-mcp-tvguide-dk
```

Requires Node.js 20 or later.

## Tools

### `list_channels`

List available channels with id and name. Supports an optional name filter.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `filter` | string | No | Case-insensitive substring to filter channel names (e.g. "dr", "tv 2", "sport") |

**Returns:** `{ count, channels[{ id, name }] }`

---

### `whats_on`

Return the programme airing on a channel now (or at a specified time).

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `channel` | string | Yes | Channel name (e.g. "DR1", "TV 2", "Kanal 5") or numeric id |
| `when` | string | No | ISO 8601 datetime or "HH:MM" (today Copenhagen). Omit for current time. |

**Returns:** A single `Programme` object:

```json
{
  "channelId": "452",
  "channelName": "DR1",
  "title": "Fodbold: VM",
  "start": "2026-06-12T21:00:00+02:00",
  "stop": "2026-06-12T22:05:00+02:00",
  "durationMinutes": 65,
  "description": "Der er store VM-drømme i Canada...",
  "categories": ["sport"],
  "live": false
}
```

---

### `tonight`

Return prime-time (19:00–23:00 Copenhagen) TV listings for today, grouped by channel.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `channels` | string[] | No | Channel names or ids to include. Defaults to the default channel set. |

**Returns:** `{ date, primetime, channels: { [channelName]: Programme[] } }`

---

### `search_program`

Find programmes by title across channels for a date.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `title` | string | Yes | Substring to search in programme titles (case-insensitive) |
| `channels` | string[] | No | Channels to search (defaults to default channel set) |
| `date` | string | No | YYYY-MM-DD date to search (defaults to today Copenhagen) |

**Returns:** `{ query, date, matchCount, programmes: Programme[] }`

## Environment Variables

| Variable | Description |
|---|---|
| `DEFAULT_CHANNELS` | Comma-separated channel names or ids for the default set used by `tonight` and `search_program`. Example: `"DR1,TV 2,TV3,Kanal 5"` |

When unset, the default is: DR1, DR2, TV 2, TV 2 News, TV3, TV3+, Kanal 4, Kanal 5, TV 2 Charlie, 6'eren.

## ARIA MCP Config

Add to your ARIA credentials / MCP config:

```json
{
  "command": "npx",
  "args": ["-y", "aria-mcp-tvguide-dk"],
  "env": {}
}
```

With a custom default channel set:

```json
{
  "command": "npx",
  "args": ["-y", "aria-mcp-tvguide-dk"],
  "env": {
    "DEFAULT_CHANNELS": "DR1,TV 2,TV3,Kanal 5"
  }
}
```

## Development

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

## Attribution & Terms

EPG data is sourced from Allente Denmark (`allente.dk`). This server is a personal/hobby project. The Allente EPG API is not a documented public API — use it in good faith and at your own risk. Check [Allente's terms](https://allente.dk/vilkaar) before any redistribution or commercial use.

## License

MIT — see [LICENSE](LICENSE).