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.
| Tier | Unlocked by | Tools |
|---|---|---|
| 0 | always | list_devices, connect_device, docs |
| 1 | device connected | build_app, install_app, launch_app, stop_app, uninstall_app, device_logs, remote_key |
| 2 | debug launch | screenshot, console_logs, eval_js |
Prerequisites
tv-mcp orchestrates the vendor toolchains — it does not replace them. You need:
| Samsung (Tizen) | LG (webOS) | |
|---|---|---|
| On this machine | Node ≥ 20 · Tizen Studio CLI (tizen, sdb on PATH) | Node ≥ 20 · webOS TV CLI: npm i -g @webos-tools/cli (ares-* on PATH) |
| On the TV, once | Developer mode: Apps → type 1 2 3 4 5 → ON → set Host PC IP to this machine's address on the TV's subnet → reboot the TV | Developer Mode app from LG Content Store (needs an LG developer account) → Dev Mode ON → note the on-screen passphrase |
| Signing | Certificate profile in Tizen Studio's certificate manager. Real TVs reject the generic Tizen distributor cert — you need a Samsung-issued cert that includes the TV's DUID (sdb shell 0 getduid) | none (dev installs ride the Dev Mode session) |
| Network | TV and this machine on the same subnet; port 26101 open only while dev mode is armed | same subnet; SSH on 9922 via the Dev Mode app; sessions expire after ~50h |
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.
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:
| Capability | Tizen | webOS |
|---|---|---|
| discover / connect | ✅ | ✅ |
| package (+sign) | ✅ | ✅ |
| install / launch / stop | ✅ | ✅ |
| debug attach (CDP) | ✅ | ✅ |
| screenshot / console / eval | ✅ | ✅ |
| remote key injection | ✅ (one-time on-screen pairing) | ✅ (one-time on-screen pairing) |
| dev-mode auto-renew | n/a | 🚧 planned |
| emulator / simulator targets | 🚧 | 🚧 |
| commercial panels (Pro:Centric, SSSP) | 🚧 | 🚧 |
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.