lg-tv-mcp

עברית: מדריך למשתמש בעברית בהמשך העמוד ומדריך התקנה מלא ב־docs/client-installation-he.md.

A local MCP server that turns an AI assistant — Claude Code, Claude Desktop, ChatGPT Work, or any MCP client — into a remote control for LG webOS smart TVs.

Everything runs on your home network: a hand-rolled SSAP websocket client with first-run pairing, the webOS button-input socket, Wake-on-LAN power-on, and mDNS re-discovery when the TV's IP changes. No cloud APIs, no accounts, no telemetry.

Tools

Tool	What it does
get_status	Power, pairing state, current app, volume — no side effects
power_on	Wake-on-LAN magic packet; TV boots in ~15 s
power_off	Turn the TV off over SSAP
set_volume	Set level 0–100, or mute/unmute
press_button	Remote buttons (arrows, OK, back, play/pause, digits…), with optional repeat
list_apps / launch_app	Enumerate and open apps (Netflix, YouTube, …)
switch_input	Switch HDMI inputs
set_channel	Change Live TV channels
type_text	Type into the focused text field
show_notification	Toast message on the TV screen
screenshot	960×540 JPEG of the current screen (DRM-protected video captures as black; app UI renders fine)
measure_sound_level	Room loudness via the laptop microphone: approximate dB SPL + band (silent/quiet/moderate/loud/very-loud). Loop it with set_volume to hit a target level
calibrate_sound_meter	One-time mic calibration against a phone SPL-meter reading; the offset persists in config.json

Requirements

• Node.js ≥ 22.13
• An LG webOS TV on the same network as the machine running the server
• For powering on while the TV is off: enable Settings → General → Turn on via Wi-Fi on the TV (wording varies by webOS version), and set your TV's MAC address in the config — see Configuration
• ffmpeg for the sound-meter tools (brew install ffmpeg); macOS microphone permission is requested from the hosting app on first capture.

Install

Not yet on npm — install from a clone:

git clone https://github.com/OmerLapidot/lg-tv-mcp.git
cd lg-tv-mcp
npm ci

Claude Code

claude mcp add lg-tv-remote --scope user -- node /absolute/path/to/lg-tv-mcp/server/index.js

Claude Desktop / any MCP client

{
  "mcpServers": {
    "lg-tv-remote": {
      "command": "node",
      "args": ["/absolute/path/to/lg-tv-mcp/server/index.js"]
    }
  }
}

ChatGPT Work (desktop plugin)

npm run plugin:release builds dist/plugin/ with the plugin manifest, skill, and icon; the release runtime pins npx -y @omerlapidot/lg-tv-mcp@<version> (npm publish is a separate release step). Installation walkthrough (Hebrew): docs/client-installation-he.md.

First run — pairing

1. Turn the TV on with the physical remote (first time only) and ask the assistant something harmless like "what's the TV status?" — get_status works unpaired.
2. The first control call (volume, buttons, apps…) pops a pairing prompt on the TV screen. Accept it with the physical remote within a minute.
3. That's it — the TV issues a client key, saved locally. The prompt never appears again unless you revoke the pairing on the TV (Settings → General → External Devices → Connection Manager).

Configuration

State lives in a single JSON file (created and updated automatically):

• macOS: ~/Library/Application Support/lg-tv-mcp/config.json
• Windows: %APPDATA%\lg-tv-mcp\config.json

Field	Meaning
hostname	mDNS name tried when the last-known IP stops answering. LGwebOSTV.local is the LG factory default, so this usually just works.
ip	Last-known IPv4 of the TV. Auto-updated whenever discovery finds the TV at a new address.
mac	The TV's Wi-Fi MAC, used only for Wake-on-LAN. The repo default is a placeholder — set your own (shown on the TV under Settings → Network → Wi-Fi Connection → Advanced) or power_on cannot wake a TV that is fully off.
clientKey	Pairing key issued by the TV on first approval; null until paired.
micCalibrationOffsetDb	Optional. dBFS→dB SPL offset stored by calibrate_sound_meter; absent until first calibration (a rough default of +100 is used, flagged calibrated: false).

Environment overrides: LG_TV_DATA_DIR (config directory), LG_TV_URL (skip discovery and connect to a fixed ws:///wss:// URL — used to point at the fake TV in tests), LG_TV_REGISTER_TIMEOUT_MS (pairing prompt timeout).

Security notes

• The client key works only from inside your LAN and can only control this TV; it contains no account credentials.
• The TV serves SSAP and screen captures over TLS with a self-signed certificate, so certificate validation is intentionally disabled for those LAN-only connections.
• Nothing leaves your network; there is no cloud relay.

Development

npm ci
npm test                # full suite against an in-process fake TV — no hardware needed
npm run plugin:release  # build dist/plugin for ChatGPT Work

Layout: server/ (config, discovery, SSAP client, input socket, Wake-on-LAN, MCP server), test/ (node:test suite plus test/fixtures/fake-tv.mjs, a scripted SSAP TV), skills/ (assistant-facing usage skill), docs/superpowers/ (original design spec and implementation plan).

Quirks worth knowing: the reported model string is a constant (LG 65NANO80VNA — the TV this was built for), and user-facing error messages are in Hebrew, since that's the household it serves. PRs welcome.

License

MIT © Omer Lapidot

---

<div dir="rtl">

שלט לטלוויזיה — עברית

תוסף מקומי שהופך את ChatGPT (או Claude) לשלט רחוק לטלוויזיית LG webOS ברשת הביתית: הדלקה וכיבוי, ווליום, פתיחת אפליקציות כמו נטפליקס ויוטיוב, החלפת כניסות HDMI, ערוצים, הקלדת טקסט, הודעות על המסך וצילום של מה שמוצג על המסך.

הכול מקומי. התקשורת היא ישירות מהמחשב לטלוויזיה ברשת הביתית (websocket מקומי + Wake-on-LAN). שום דבר לא עובר בענן.

התקנה

המדריך המלא: docs/client-installation-he.md. בקצרה:

1. מתקינים את התוסף שלט לטלוויזיה ביישום ChatGPT Work למחשב.
2. מפעילים מחדש את ChatGPT, פותחים משימה וכותבים: "מה מצב הטלוויזיה?".
3. בפקודת השליטה הראשונה יופיע על מסך הטלוויזיה חלון אישור — מאשרים פעם אחת עם השלט הפיזי, וזהו.
4. כדי שההדלקה מרחוק תעבוד, מפעילים בטלוויזיה את ההגדרה Turn on via Wi-Fi.

</div>