lg-tv-use-mcp
Allows launching and interacting with the YouTube app on an LG webOS TV, including opening specific YouTube video IDs and performing native YouTube searches.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lg-tv-use-mcp Open YouTube and search for a ten-minute stretching routine."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
LG TV Use

A local MCP server and CLI for LG webOS TVs. Control apps, remote keys, pointer, text and power over your LAN. Turn visually checked app operations into reusable Python addons, so known routes can run without taking a screenshot at every step.
Experimental, version 0.3.1. This is an agent tool, not a continuously running autonomous agent. An agent or operator must inspect new screens before learning routes. Native foreground state and predicted UI state do not prove what is playing or which control has focus.
Features
17 MCP tools over stdio, plus a CLI and persistent JSON-lines session.
Native app launch, advertised app search, LG browser URLs and YouTube video IDs.
Bounded remote keys, relative pointer motion, clicks, scrolling and text input.
Per-device pairing, model/MAC identity checks, power-off and Wake-on-LAN with native power-state readback.
App/firmware-scoped route learning, generated local addons and visual fallback for unknown or stale routes.
UI recipes with an exact observed starting page, focus, keyboard and modal state. Replays skip images only when that tracked context is still valid.
No automatic replay of a command whose delivery is uncertain.
Related MCP server: @mokuichi147/webos-mcp
Requirements
Python 3.11+ on macOS or Linux. Windows is unsupported (
fcntlfile locking).An LG webOS TV with the second-screen service reachable on the same LAN.
A private IPv4 address for the TV; multicast discovery is optional.
Physical acceptance of the LG TV Use pairing prompt on each TV.
For waking: supported network standby/mobile power-on settings and a suitable LAN broadcast address. This varies by model and network.
No LG cloud account, developer mode, root access or API key is required by this tool. See compatibility and validation for tested behavior and limits.
Install and pair
This release is distributed through GitHub; there is no project PyPI release.
git clone https://github.com/iJaack/lg-tv-use.git
cd lg-tv-use
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps .
# Optional: discover second-screen advertisements, without scanning the subnet.
.venv/bin/lg-tv-use discover
# Replace the example address with the one shown in your TV network settings.
export TV_HOST=192.168.1.100
.venv/bin/lg-tv-use pairAccept LG TV Use on the TV within 45 seconds. --host overrides TV_HOST.
There is no implicit target address and ordinary commands never initiate pairing.
Optionally add --model YOUR_EXACT_MODEL to reject a different native model before
saving credentials or executing commands.
.venv/bin/lg-tv-use apps
.venv/bin/lg-tv-use --capture always observe
.venv/bin/lg-tv-use launch youtube.leanback.v4
.venv/bin/lg-tv-use search '10 minute full body stretch'
.venv/bin/lg-tv-use browser https://example.com
.venv/bin/lg-tv-use --capture never press BACKConnect an MCP client
Use the installed lg-tv-use-mcp executable, with TV_HOST set in the client
configuration. An absolute executable path avoids GUI clients' PATH differences.
Copy and edit examples/mcp.json for clients using mcpServers.
For Codex:
codex mcp add lg-tv-use --env TV_HOST=192.168.1.100 -- /absolute/path/to/lg-tv-use/.venv/bin/lg-tv-use-mcpRestart or reload an already running MCP session after configuration or schema changes. Registering the server and loading its tools are separate steps. The server opens no inbound HTTP port on the host.
Example requests to your agent:
“Show me what is on the TV.”
“Open YouTube and search for a ten-minute stretching routine.”
“Inspect this app's search screen and save a reusable route.”
Full tool arguments, capture policies and examples are in the tool reference.
Learning routes
For a native operation, run tv_app_action with capture="auto". A new route
captures a discovery image. After inspecting the result, call tv_learn with its
witness ID and notes describing what the image actually proves. If the first image
shows loading, wait and use tv_observe(capture="always") before learning.
Subsequent matching operations use a generated wrapper and lightweight native readback, without images. Changed app metadata, app version, TV or available firmware scope requires discovery again.
For internal UI routes:
Inspect
tv_observe(capture="always")and name its exact starting state withtv_ui_anchor. Include the underlying page, focused control, keyboard and modals.Use
tv_ui_recordfor a bounded sequence of keys/text/waits and a final image.Inspect the final image. Learn only a result matching the declared destination.
Use
tv_ui_runto replay from the same tracked origin. Unknown or expired context returns a screenshot without executing the recipe.
The witness must be at most 30 seconds old when anchoring. Context expires after
60 seconds and clears on untracked commands, reconnects, new images or TV changes.
External remote input cannot always be detected: observe again after anyone uses
the physical remote. tracked_state is a prediction, not a UI accessibility tree.
See architecture for the generation and verification model.
Multiple TVs and power
Pair and register each TV while it is on:
.venv/bin/lg-tv-use --host 192.168.1.100 register 'Living Room' --broadcast 192.168.1.255
.venv/bin/lg-tv-use --host 192.168.1.101 pair
.venv/bin/lg-tv-use --host 192.168.1.101 register 'Bedroom' --broadcast 192.168.1.255
.venv/bin/lg-tv-use --host 192.168.1.101 power status
.venv/bin/lg-tv-use --host 192.168.1.101 power off
.venv/bin/lg-tv-use --host 192.168.1.101 power onChoose a broadcast appropriate for your own subnet. Registration stores native
network MACs and a stable device credential copy. In MCP, use tv_devices,
tv_select(device="Bedroom") and tv_power(operation="on").
power off sends the native command once. power on sends bounded Wake-on-LAN
packets and may also use the native wake handshake when standby remains reachable.
Both attempt a native state readback. UDP delivery is not an acknowledgement and
an unreachable endpoint alone is not proof of power-off. If wake cannot be
verified, inspect the TV and its standby/network settings.
Configuration and privacy
Setting | Purpose |
| Required RFC1918 IPv4 TV address. |
| Optional expected native model. |
| Credentials/state root. Default: |
| Optional addons directory; registry lives there too, credentials remain in |
Credential files use mode 0600; the credential directory uses 0700. Generated
addons and registry writes are atomic and use local file locks. CLI screenshots
are written to outputs/ in the current directory with mode 0600. MCP images are
returned to the calling client: that client or its model provider may receive them.
Credentials, profiles, device identifiers and captures should never be committed.
Control sockets use TLS certificate pinning after explicit first pairing; they do not fall back to plaintext WebSockets. Some TVs return screenshot URLs over HTTP, so image transport can be unencrypted on the LAN. Downloads are restricted to the selected TV, with redirects refused and a size cap. See SECURITY.md.
Troubleshooting
No TV discovered: check its IP directly; multicast advertisements can be absent, stale or blocked. Only private IPv4 targets are supported.
Pairing rejected/timed out: keep the TV on and accept its prompt; the tool does not treat missing acceptance as a successful connection.
Certificate changed: verify the physical TV before removing only its stale credential file and pairing again.
pairdoes not silently replace a pinned certificate.Text ignored in YouTube: use native
search; generic LG IME is app-dependent.Screenshot missing/black: firmware and protected video may prevent capture.
Unexpected UI: observe again; a known app launch does not prove a known screen.
TV won't wake: check network standby/mobile power-on support and broadcast; Wi-Fi wake is not guaranteed on every model.
Development
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q tv_use.py tv_runtime.py tv_power.py app_learning.py tv_cli.py server.py testsTests use mocks and a temporary-state MCP subprocess; they send no TV commands. CI checks Python 3.11/3.14 on macOS/Linux and builds/installs the package. Physical TV acceptance remains a separate check. See CONTRIBUTING.md and CHANGELOG.md.
License and acknowledgements
MIT, copyright Jaack. Independent project, not affiliated with LG or the app vendors. The webOS second-screen protocol was studied through LG Connect SDK. Downloaded SDK sources and private device evidence are not included in this repository. Runtime dependencies retain their own licenses.
Brand assets: transparent logo, cover, and generation prompts.
Available Tools
17 toolstv_app_actionC
Execute bounded native app route. Search uses advertised metadata; URL is LG browser only; video accepts YouTube ID. Unknown routes capture once for learning.
Inputs: app_id (required), value, capture, operation. Returns: result
tv_appsC
Installed app versions, learned routes and native routes requiring visual discovery.
Inputs: no named parameters.
tv_clickC
Click current pointer position; requires a known target or fresh visual observation.
Inputs: capture. Returns: result
tv_devicesB
Known paired TVs. Select by name/ID; duplicate IPv4 addresses are ambiguous.
Inputs: no named parameters.
tv_discoverA
Find LG TVs without pairing or subnet scanning.
Inputs: no named parameters. Returns: result
tv_launchC
Launch installed non-stub app; learned route avoids image capture.
Inputs: app_id (required), capture. Returns: result
tv_learnC
After visually verifying the latest native action or UI recording screenshot, compile its route into a reusable addon. Include what the image actually proved in notes.
Inputs: notes (required), witness_id (required).
tv_moveC
Move relative pointer. Inspect unknown target before clicking.
Inputs: dx (required), dy (required), capture. Returns: result
tv_observeB
Lightweight app/audio state. Auto captures unknown apps; always requests a fresh screen.
Inputs: capture. Returns: result
tv_powerB
Power off natively or wake registered MACs, then verify native power state. Unreachable is not proof of power off. Wake requires TV network-standby support.
Inputs: operation (required), wait_seconds.
tv_pressC
Bounded remote key; foreground state cannot identify focused control. Observe unknown navigation visually.
Inputs: button (required), capture. Returns: result
tv_scrollC
Bounded scrolling, with lightweight state and automatic unknown-app fallback.
Inputs: dy (required), capture. Returns: result
tv_selectB
Select a registered TV by name or ID and verify native device identity. Never pair implicitly.
Inputs: device (required).
tv_typeB
Send focused-field text. Some apps including YouTube ignore it; acknowledgement does not verify insertion.
Inputs: text (required), capture. Returns: result
tv_ui_anchorB
Name exact page, focus, keyboard and modal state after inspecting a screenshot taken within 30 seconds. Selected tab alone is insufficient. Context expires after 60 seconds or an untracked command/reconnect.
Inputs: state (required), witness_id (required).
tv_ui_recordB
From an inspected anchored state, run 1-20 press/wait/text/replace_text/submit steps and capture the result once. Inspect then tv_learn; text $VALUE parameterizes the route. Never learn loading as completed content, nor purchases, account edits or consent routes.
Inputs: name (required), steps (required), to_state (required), from_state (required), +1 more. Returns: result
tv_ui_runC
Run generated UI addon without images only from its tracked origin and exact app version. Unknown/expired context returns a screenshot without executing. Tracked state is predicted, not TV focus readback; re-observe after external remote use.
Inputs: name (required), app_id (required), value. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target distinct actions (tv_press vs tv_click vs tv_move vs tv_scroll), but several boundaries blur: tv_ui_anchor and tv_observe both inspect state, tv_ui_record and tv_ui_run both execute UI sequences, and tv_launch overlaps with tv_app_action for starting apps. The verbose descriptions help separate them, but an agent could still misselect.
Every tool uses a consistent tv_ prefix with snake_case and a predictable verb/noun structure (tv_press, tv_move, tv_learn, tv_app_action, tv_ui_record). The tv_ui_* group is a coherent sub-namespace, and no conventions are mixed.
17 tools is slightly heavy but defensible for a domain spanning discovery, pairing, power, app launch, low-level input, and a UI-recording/learning pipeline. Each tool maps to a real capability, with little obvious redundancy.
The surface covers discovery, selection, power, app enumeration/launch, and a full input+observe+record+learn lifecycle, which is strong for TV control. Gaps remain around explicit volume/audio and channel control, though tv_observe reports audio state.
Maintenance
Related MCP Connectors
Your team's custom tools and skills in every agent, through one MCP connection.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Control Android TV from any AI. 38 MCP tools: playback, recap, recommend, smart-home, schedules.
Remote MCP server for Web3TV creators — manage your account over MCP.
Related MCP Servers
- AlicenseCqualityCmaintenanceAn MCP server for controlling LG webOS TVs via SSAP protocol, enabling AI clients to adjust settings, switch inputs, launch apps, and more.3755 npm3MIT
- AlicenseBqualityCmaintenanceEnables controlling LG webOS TVs via MCP, including apps, volume, remote keys, mouse, inputs, channel selection, program guides, screenshots, and Wake-on-LAN power on, without installing additional software on the TV.3915 npmMIT
- AlicenseAqualityBmaintenanceLets MCP clients and the command line control LG webOS TVs directly over the local network, discovering and pairing TVs and then launching apps, switching inputs, playing YouTube videos, adjusting volume, pressing remote keys, showing messages, and powering the TV on or off.182MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate and view the Vega Virtual Device through MCP: press remote keys, take screenshots, record video with sound, wait for screen changes, and check the TV safe area.21 npmMIT