tv-mcp
Build, deploy, and debug Smart TV web apps from any AI agent.
tv-mcp is a Model Context Protocol server that gives MCP clients (Claude Code, Cursor, VS Code, ...) hands-on access to real Samsung Tizen and LG webOS televisions: package and sign apps, install them on test TVs, take screenshots, read the JS console, evaluate code in the running app, and press remote-control keys.
The goal: an agent loop of edit code → build → install → screenshot → read console → fix that runs hands-free on physical TVs.
Who this is for
Smart TV development has the worst inner loop in web development: two vendor SDKs, certificate ceremonies, dev-mode timers, and a screen on the other side of the room. This hits hardest in hospitality and B2B TV — hotel IPTV, cruise ships, hospitals, digital signage, sports bars — where teams ship one web app to fleets of mixed Samsung/LG panels.
If that's you, this project is for you.
How it works
Your TV app is a web app in a native wrapper (.wgt / .ipk). Both platforms expose the webview's Chrome DevTools Protocol remote inspector. So tv-mcp splits into:
- a platform plane per vendor (build/sign/install/launch via
tizen/sdbandares-*CLIs), and - a shared CDP plane (screenshot, console, JS eval) that works identically on both — because underneath it's just Chromium.
MCP client ── stdio ── tv-mcp
├── TizenDriver → tizen / sdb → Samsung TV
├── WebOSDriver → ares-* → LG TV
└── CdpBridge → DevTools Protocol → the app's webview (both)
Progressive disclosure
A fresh session exposes only 3 tools (list_devices, connect_device, docs). Connecting a device unlocks the app-lifecycle tier; launching with debug: true unlocks the inspector tier (screenshot, console_logs, eval_js). Deep platform knowledge (Tizen signing/DUIDs, webOS dev-mode expiry, pairing flows) ships as MCP resources fetched on demand — your agent's context stays small until it actually needs the detail.
Prerequisites
tv-mcp orchestrates the vendor toolchains — it does not replace them. You need:
Common trap (learned on real hardware): a multi-homed machine has several IPs — the Host PC IP on the TV must be the one on the TV's subnet, or the TV silently drops every connection. docs topic device-setup has the full checklist; the server's errors point there when connect/install fails.
Not sure your setup is right? Ask the agent to run doctor — one pass over toolchains, signing profiles (it distinguishes Samsung-issued certs from the generic SDK cert that real TVs reject), and TV reachability, with a remedy for every failing item.
Quick start
npm install
npm run build
cp devices.example.yaml devices.yaml # edit for your TVs and project
Claude Code:
claude mcp add tv -- node /path/to/tv-mcp/dist/index.js --config /path/to/devices.yaml
Then, in a session:
connect to lab-samsung-q80, build the xtv project for tizen, install and launch it in debug mode, and screenshot it
Status
Early. Honest capability matrix:
Roadmap
- v0.2 — ✅ remote-key pairing (Samsung remote WS API, LG SSAP)
- v0.2.x — webOS dev-mode auto-renew
- v0.3 — Android TV driver (#1): adb platform plane + the same CDP debug plane (Android TV webapps are Chromium WebViews too)
- v0.3 — Tizen emulator + webOS simulator targets, CI-friendly headless mode
- v0.4 — streamable-HTTP transport + device locking: one shared TV lab, whole team's agents
- v1.0 — commercial hospitality panels (LG Pro:Centric / webOS Signage, Samsung SSSP / HTV)
Sponsoring
Commercial-panel support (Pro:Centric, SSSP) needs hardware and vendor-portal access that individual maintainers don't have. If your company ships hospitality TV apps and wants this to exist, sponsorship or hardware loans move the roadmap directly — see FUNDING or open a discussion.
Contributing
PRs welcome — see CONTRIBUTING.md. The TVDriver interface in src/types.ts is the extension point; a Vizio/Roku/Android TV driver would slot right in.