# XMLTV MCP Server

MCP server for accessing Tunarr XMLTV feed data. Provides tools to query TV channels, programmes, schedules, and search content.

## Features

- **get_channels** - List all available TV channels
- **get_now_playing** - See what's currently playing on all channels
- **get_schedule** - Get upcoming schedule for a specific channel
- **search_programmes** - Search for programmes by title or description
- **get_programme_details** - Get detailed information about a specific programme

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the XMLTV URL via environment variable (defaults to `http://tunarr.lan/api/xmltv.xml`):

```bash
export XMLTV_URL="http://your-tunarr-instance/api/xmltv.xml"
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration file:

### macOS
`~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows
`%APPDATA%/Claude/claude_desktop_config.json`

Configuration:

```json
{
  "mcpServers": {
    "xmltv": {
      "command": "node",
      "args": ["/absolute/path/to/xmltv-mcp/dist/index.js"],
      "env": {
        "XMLTV_URL": "http://tunarr.lan/api/xmltv.xml"
      }
    }
  }
}
```

After updating the configuration, restart Claude Desktop.

## Tools

### get_channels

Lists all available channels.

**Example:**
```
What channels are available?
```

**Response:**
```json
[
  {
    "id": "C1.49.tunarr.com",
    "name": "Animation (Simpsons, South Park, Futurama, Rick & Morty, Courage)"
  },
  {
    "id": "C2.50.tunarr.com",
    "name": "Sitcom (Big Bang Theory, Friends, How I Met Your Mother)"
  }
]
```

### get_now_playing

Shows what's currently playing on all channels.

**Example:**
```
What's on TV right now?
```

**Response:**
```json
[
  {
    "channel": {
      "id": "C1.49.tunarr.com",
      "name": "Animation"
    },
    "programme": {
      "title": "The Simpsons",
      "subtitle": "Homer's Odyssey",
      "start": "20251221180000 +0000",
      "stop": "20251221183000 +0000"
    }
  }
]
```

### get_schedule

Get upcoming programmes for a specific channel.

**Parameters:**
- `channel_id` (required) - Channel ID (e.g., "C1.49.tunarr.com")
- `hours_ahead` (optional) - Hours to look ahead (default: 24)

**Example:**
```
Show me the schedule for the Animation channel for the next 12 hours
```

### search_programmes

Search for programmes by title, subtitle, or description.

**Parameters:**
- `query` (required) - Search term

**Example:**
```
Search for Simpsons episodes
```

**Response:**
```json
[
  {
    "channel": {
      "id": "C1.49.tunarr.com",
      "name": "Animation"
    },
    "title": "The Simpsons",
    "subtitle": "Bart the Genius",
    "start": "20251221190000 +0000",
    "stop": "20251221193000 +0000"
  }
]
```

### get_programme_details

Get detailed information about a specific programme.

**Parameters:**
- `channel_id` (required) - Channel ID
- `start_time` (required) - Programme start time in XMLTV format (YYYYMMDDHHMMSS +0000)

**Example:**
```
Get details for the programme on C1.49.tunarr.com at 20251221180000 +0000
```

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev
```

## Data Caching

The server caches XMLTV data for 5 minutes to reduce load on your Tunarr instance. The cache automatically refreshes when expired.

## Channel Information

Based on your Tunarr setup, the following channels are available:

1. **C1.49.tunarr.com** - Animation (Simpsons, South Park, Futurama, Rick & Morty, Courage)
2. **C2.50.tunarr.com** - Sitcom (Big Bang Theory, Friends, How I Met Your Mother)
3. **C3.51.tunarr.com** - Space (SEA, Anton Petrov, Cool Worlds, Astrum - YouTube science)
4. **C4.52.tunarr.com** - Classic Sci-Fi (Twilight Zone, X-Files)

## License

MIT