XMLTV MCP Server

# 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