{"id":"3a11cdc9-9bd2-45f2-a961-da2933e78091","slug":"catt-mcp","kind":"mcp","name":"catt-mcp","summary":"MCP server to cast YouTube and media URLs to Chromecast/DLNA devices via catt, with PC and TV dual-screen sync","owner":"amineutron","repoUrl":"https://github.com/amineutron/catt-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-08T18:59:15.000Z","addedAt":"2026-10-14T05:25:34.387Z","logoUrl":"https://avatars.githubusercontent.com/u/56112165?u=64e47dcb2aeb11f60136bdc1761453c725d48e9c&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":["catt","chromecast","dlna","home-automation","python","youtube","local-first","self-hosted"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T14:42:19.021Z","sample":false,"url":"https://conduits.dev/tools/catt-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"catt-mcp"},"requirements":{"env":[{"name":"CATT_DEVICE","secret":false,"required":false,"description":"Name or IP of the default Chromecast / DLNA device"},{"name":"TV_HOST","secret":false,"required":false,"description":"Optional Android TV IP, used to wake the screen over ADB before casting"},{"name":"ADB_PATH","secret":false,"required":false,"description":"Path to the adb binary if not on PATH"}],"upstreamMayCharge":false},"tools":null,"readme":"# catt-mcp\n<!-- mcp-name: io.github.amineutron/catt-mcp -->\n\n[![tests](https://github.com/amineutron/catt-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/amineutron/catt-mcp/actions/workflows/tests.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n\nMCP server for casting YouTube videos and media to Chromecast/DLNA devices via [catt](https://github.com/skorokithakis/catt).\n\nExposes 15 tools covering YouTube casting, playback control, dual-screen sync, and device discovery.\n\n## Demo\n\n![MCP client: the 15 tools, then cast_scan finding the TV](docs/assets/demo.gif)\n\nRecorded on the real network with [`docs/demo/record.sh`](docs/demo/record.sh): a minimal MCP client ([`docs/demo/mcp_demo.py`](docs/demo/mcp_demo.py)) starts the server over stdio with `CATT_DEVICE` in the environment, lists the tools and calls `cast_scan` (read-only). Private IP addresses are replaced with documentation addresses.\n\n## Tools\n\n<!-- tools:start -->\n| Outil | Rôle |\n|---|---|\n| `cast_youtube` | Caste une video YouTube sur la TV (URL ou ID de video) |\n| `cast_url` | Caste une URL quelconque (video, audio, stream) sur la TV |\n| `cast_stop` | Arrete le cast en cours sur la TV |\n| `cast_pause` | Met en pause le cast en cours |\n| `cast_resume` | Reprend la lecture du cast |\n| `cast_volume` | Regle le volume du cast (0-100) |\n| `cast_seek` | Avance ou recule dans la video |\n| `cast_status` | Retourne le statut du cast en cours |\n| `cast_scan` | Scanne les devices Chromecast/DLNA disponibles sur le reseau |\n| `cast_info` | Retourne les infos detaillees du media en cours |\n| `cast_browser` | Caste la video de l'onglet actif de Firefox sur la TV (YouTube, Twitch, etc.) |\n| `cast_browser_dual` | Lance la video sur PC (Firefox) ET TV simultanement avec synchronisation (pour LightBeat) |\n| `cast_dual_resync` | Resynchronise PC et TV en relancant la TV a la position Firefox |\n| `cast_dual_stop` | Arrete le dual cast et le watcher de synchronisation |\n| `cast_dual_offset` | Ajuste le decalage TV (positif=TV en avance, negatif=TV en retard) |\n<!-- tools:end -->\n\n### YouTube ID extraction\n\n`_extract_video_id` (URL `watch?v=`, `youtu.be/`, `shorts/` or a bare 11-character ID, anything else rejected before it reaches `catt`/ADB) is deliberately duplicated in [pylips-mcp](https://github.com/amineutron/pylips-mcp) (`youtube_video`, TV app with Premium account). Both servers stay installable on their own; each one tests its copy with the same table of cases (`tests/test_youtube_id.py`). Decision recorded on 2026-09-20.\n\n## Requirements\n\n- Python 3.10+\n- [catt](https://github.com/skorokithakis/catt): `pip install catt`\n- [yt-dlp](https://github.com/yt-dlp/yt-dlp): `pip install yt-dlp`\n- A Chromecast or DLNA-compatible device on the same network\n- `lz4` (optional, for cache compression): `pip install lz4`\n\n### Dual cast (Linux + Hyprland)\n\n`cast_browser`, `cast_browser_dual`, `cast_dual_resync`, `cast_dual_stop` and\n`cast_dual_offset` drive Firefox from the running desktop session. They are\nadvertised **only** when the required binaries are present:\n\n- [Hyprland](https://hyprland.org/) with `hyprctl` in `PATH`\n- `playerctl` for MPRIS playback control\n- Firefox holding the video to mirror\n- `lz4` (Python) to read Firefox's session cache\n\nWithout them the server starts normally and simply does not expose these five\ntools, instead of failing when they are called.\n\n## Installation en une ligne\n\n```bash\nuvx catt-mcp                 # depuis PyPI ; avant publication : uvx --from git+https://github.com/amineutron/catt-mcp catt-mcp\n```\n\nConfiguration Claude Desktop / Claude Code (`mcpServers`) :\n\n```json\n{ \"catt\": { \"command\": \"uvx\", \"args\": [\"catt-mcp\"], \"env\": { \"CATT_DEVICE\": \"Living Room TV\" } } }\n```\n\n## Setup\n\n### 1. Install dependencies\n\n```bash\npip install mcp catt yt-dlp\n```\n\n### 2. Discover your device\n\n```bash\ncatt scan\n```\n\nNote the device name (e.g. `55OLED705/12`, `Living Room TV`).\n\n### 3. Configure\n\nCopy `config.example.yaml` to `config.yaml`:\n\n```yaml\ncatt:\n  device: \"55OLED705/12\"   # Name from catt scan\n```\n\n### 4. Run\n\n```bash\ncatt-mcp                      # installed (pip, uvx) ; `catt-mcp --help` lists the settings\npython -m catt_mcp            # same thing, from any environment where the package is installed\npython server.py              # from a clone, without installing (thin launcher, code in catt_mcp/)\n```\n\nOr with environment variable:\n\n```bash\nCATT_DEVICE=\"55OLED705/12\" catt-mcp\n```\n\nThe code lives in the `catt_mcp` package (`catt_mcp/server.py`, `catt_mcp/sync_watcher.py`),\nso it can be installed next to other MCP servers without module name clashes.\n\nThe dual-screen tools (`dual_cast`, `dual_resync`, `dual_offset`) drive the TV through\nADB and need its IP address. Set it with `TV_HOST` (or `tv.host` in `config.yaml`),\nfor example `TV_HOST=\"192.0.2.10\"`; the built-in default is only a placeholder.\n\n## Claude Desktop Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"catt\": {\n      \"command\": \"python3\",\n      \"args\": [\"/path/to/catt-mcp/server.py\"],\n      \"env\": {\n        \"CATT_DEVICE\": \"55OLED705/12\"\n      }\n    }\n  }\n}\n```\n\n## License\n\nMIT\n\n## Part of the Lyra ecosystem\n\n| Dépôt | Rôle |\n|---|---|\n| [lyra](https://github.com/amineutron/lyra) | assistant DevOps vocal, local par défaut (AGPL-3.0) |\n| [fedora-agents](https://github.com/amineutron/fedora-agents) | MCP : machines virtuelles KVM et sauvegardes |\n| [mcp-tracking](https://github.com/amineutron/mcp-tracking) | MCP + API + tableau de bord des tâches longues |\n| [neutroncore](https://github.com/amineutron/neutroncore) | hub PWA du homelab |\n| [hue-mcp](https://github.com/amineutron/hue-mcp) | MCP Philips Hue (fork de ThomasRohde/hue-mcp) |\n| [pylips-mcp](https://github.com/amineutron/pylips-mcp) | MCP TV Philips |\n| [denon-mcp](https://github.com/amineutron/denon-mcp) | MCP ampli Denon |\n| [catt-mcp](https://github.com/amineutron/catt-mcp) | MCP Chromecast et DLNA |\n"}