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

npm install
npm run build

Configuration

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

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:

{
  "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:

[
  {
    "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:

[
  {
    "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:

[
  {
    "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

# 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