Skip to main content
Glama

📺 lgtv-mcp

Let Claude run your LG TV over the home network, and wake you up with a morning briefing on it.

Python 3.12+ uv MCP SDK 2.x aiowebostv webOS 25 macOS Tools License: MIT

Quick start · Tools · Morning briefing · Architecture · Privacy · Troubleshooting · Development


A local MCP server that turns an LG webOS TV into something Claude can operate. Claude can:

  • power the TV on and off

  • open apps, YouTube videos and searches

  • change volume, inputs and channels

  • press remote buttons

  • show on-screen notifications

It talks to the TV over webOS's SSAP websocket (secure port 3001) through aiowebostv, the library Home Assistant uses. It also wakes the TV with Wake-on-LAN.

On top of that sits a weekday morning briefing: date, weather, today's calendar and headlines on the big screen at 07:30.

Tested live on an LG 55UT80406LA (UT80, 2024), webOS 25 (10.3.2), from a Mac mini on the same Wi-Fi.

✨ Highlights

🔌 Zero-config discovery

Finds the TV with SSDP and reads its MAC from ARP. If DHCP moves the TV, it finds it again

🔐 Secrets stay local

The pairing key is in ~/.config/lgtv/ (0600). The calendar address is in the macOS Keychain. Neither is in the repo

🛟 Readable failures

"The TV is off (Active Standby). Call power_on first." instead of a stack trace

🌅 Morning briefing

A 1080p dark page, shown in the TV's browser, that stays out of the way if you're already watching something

🍎 Native scheduling

launchd agents, a pmset wake schedule and a rotating log file. No cron

Related MCP server: @mokuichi147/webos-mcp

🚀 Quick start

git clone https://github.com/Laksh-star/lgtv-mcp.git && cd lgtv-mcp
uv sync
uv run lgtv-pair                 # finds the TV. Accept the prompt on screen within 60 s

lgtv-pair 192.168.1.x --force re-pairs with a specific IP.

Pairing writes ~/.config/lgtv/config.json with host, mac and client_key. To override these, set LGTV_HOST, LGTV_MAC or LGTV_CONFIG_DIR.

Connect it to Claude

claude mcp add --scope user lgtv -- /opt/homebrew/bin/uv run --directory /path/to/lg-tv lgtv-mcp
claude mcp list     # lgtv: ✔ Connected

The app keeps claude_desktop_config.json in memory and saves over outside edits while it runs. So quit it fully (Cmd+Q) first, then run:

/opt/homebrew/bin/uv run --directory /path/to/lg-tv python scripts/install_claude_desktop.py

The installer:

  • refuses to run while the app is open

  • backs up the config to claude_desktop_config.json.bak-<timestamp>

  • adds only the lgtv entry, leaving other servers untouched

  • writes absolute paths, because the app doesn't use your shell PATH

Reopen the app, and lgtv appears under Connectors. Its log is at ~/Library/Logs/Claude/mcp-server-lgtv.log.

Then just ask: "Turn on the TV and play lofi hip hop on YouTube."

🧰 Tools

Area

Tool

What it does

⚡ Power

power_on

Wake-on-LAN, plus SSAP turnOn from standby. Waits until the TV is on (up to 30 s)

power_off

Puts the TV in standby

screen_off / screen_on

Panel off or on while audio keeps playing

ℹ️ Status

get_status

Power, current app, input, volume, mute, sound output, media play state, model

🔊 Volume

set_volume · volume_up · volume_down · mute

Level 0–100, steps, mute/unmute/toggle

🎛️ Inputs

list_inputs · switch_input

HDMI list with connected and active flags. Switch by id or label (HDMI 3)

📱 Apps

list_apps · launch_app · close_app

Launch by id or title, with content_id, params, youtube_video, youtube_search

▶️ Media

media_control

play · pause · stop · rewind · fast_forward

📡 Live TV

channel_up · channel_down

Opens Live TV if needed and reports the new channel

🕹️ Remote

press_button

HOME, BACK, OK, arrows, MENU, digits, colours… with repeat

⌨️ Text

type_text

Types into the focused field via the LG keyboard. YouTube ignores it, so use youtube_search there

💬 Notify

show_toast

On-screen notification bubble

🌅 Briefing

show_briefing

Shows the morning briefing now, turning the TV on if needed

Opening a specific title

launch_app passes content_id straight to the app, so a deep link can start a film instead of stopping at the app's home screen. Tested on the TV above:

App

content_id

Status

Netflix

m=https://www.netflix.com/watch/<NETFLIX_ID>&source_type=4

✅ Opens the title. Take the ID from the title's web URL (netflix.com/title/<id>)

YouTube

use youtube_video / youtube_search instead

✅

Prime Video, JioHotstar, Zee5

Not tested yet

The app may stop at its "Who's watching?" profile screen first. Claude can't see the screen, so it can't pick a profile reliably.

NOTE

WithTV On With Mobile enabled, the TV usually sits in Active Standby after power_off, and power_on brings it back in about a second. After a while it can drop off the network entirely. Then Wake-on-LAN wakes it in about 15 seconds. Tools that need a lit screen refuse in standby rather than "succeeding" against a dark TV.

🌅 Morning briefing

Every weekday at 07:30 the TV shows a full-screen page, refreshed every 5 minutes:

Panel

Source

Day, date and a live clock

This Mac (Asia/Kolkata)

Weather now, high and low, chance of rain, sunrise and sunset

Open-Meteo (no API key)

Today's events, with the next one highlighted

Google Calendar secret iCal address, kept in the Keychain

3 headlines each, India and World

RSS from The Hindu (National) and BBC News (World)

What a run does depends on the TV:

The TV is…

Result

⚫ Off

Turns on, then opens the page in the webOS browser

🏠 On Home or the screen saver

Opens the page

🎬 Playing something, on Live TV or HDMI, or in an app

Leaves the screen alone and shows a toast: "Morning briefing: 2 meetings today, next at 10:00 · 29°C, rain 0%"

  • Auto turn-off: if the page is still on screen after 30 minutes, the TV turns off. If someone switched to something else, it stays on.

  • Fallback: if the browser doesn't load the page, the briefing arrives as a few toasts instead.

  • One source failing doesn't stop the rest: that panel says "unavailable", and the log records why.

Commands

uv run briefing now                 # show it now, using the 07:30 rules (a toast if the TV is busy)
uv run briefing now --force         # take over the screen anyway
uv run briefing now --auto-off 1    # also test the auto turn-off after 1 minute
uv run briefing preview             # render the page to ~/Library/Caches/lg-tv-briefing/preview.html
uv run briefing status              # agents, Keychain check, wake schedule, recent log lines
uv run briefing install             # (re)install the launchd agents from the settings file
uv run briefing uninstall           # turn the briefing off

From Claude, say "show my briefing on the TV", which uses the show_briefing tool.

Calendar setup (once)

  1. Go to Google Calendar → ⚙️ Settings → your calendar → Integrate calendar → copy Secret address in iCal format.

  2. Store it in the login Keychain. The command prompts for the address, so it never touches a file or your shell history:

    security add-generic-password -U -s lgtv-briefing -a google-calendar-ics -w

    If you saved it under another name in Keychain Access, set keychain_service and keychain_account ("" means any account) under [calendar] in the settings file.

  3. If macOS asks whether security may read the item, choose Always Allow, so the unattended 07:30 run can read it.

Repeating events, moved or skipped occurrences, all-day events and other time zones all resolve to local time. Cancelled and declined events are left out.

Change the time or content

Everything lives in ~/.config/lgtv/briefing.toml:

[location]               # weather city
name = "New Delhi"       # your city; find coordinates on open-meteo.com
latitude = 28.6139
longitude = 77.2090
timezone = "Asia/Kolkata"

[schedule]               # after editing, run:  uv run briefing install
weekdays = [1, 2, 3, 4, 5]   # 1 = Monday … 7 = Sunday
time = "07:30"
auto_off_minutes = 30        # 0 = never

[[feeds]]                # add, remove or reorder as you like
name = "India"
url = "https://www.thehindu.com/news/national/feeder/default.rss"
count = 3

Content changes appear within 5 minutes. Schedule changes need uv run briefing install, which also prints the matching pmset line.

Wake the Mac first (optional)

sudo pmset repeat wakeorpoweron MTWRF 07:25:00     # check it with: pmset -g sched

This replaces any other repeating wake schedule. If the Mac is shut down, it powers on at that time, but the briefing only runs once you're logged in.

Turn it off

uv run briefing uninstall     # removes both launchd agents
sudo pmset repeat cancel      # removes the Mac wake schedule

🏗️ Architecture

Control path

flowchart LR
    subgraph Mac["🖥️ Mac mini"]
        CC["Claude Code"]
        CD["Claude desktop"]
        S["lgtv-mcp<br/>server.py · 21 tools"]
        T["TV manager<br/>tv.py"]
        CFG[("~/.config/lgtv/<br/>config.json")]
        CC -- "stdio (MCP)" --> S
        CD -- "stdio (MCP)" --> S
        S --> T
        T <--> CFG
    end
    subgraph Home["🏠 Home Wi-Fi"]
        TV["📺 LG webOS TV"]
    end
    T -- "SSAP over wss :3001<br/>commands + live state" --> TV
    T -. "Wake-on-LAN (UDP :9)" .-> TV
    T -. "SSDP discovery (UDP :1900)" .-> TV

Morning briefing

flowchart TB
    subgraph Mac["🖥️ Mac mini"]
        L1["⏰ launchd<br/>local.lgtv.briefing<br/>Mon–Fri 07:30"]
        L2["launchd<br/>local.lgtv.briefing.server"]
        R["briefing run<br/>show.py"]
        W["page server :8765<br/>web.py · page.py"]
        G["gather()<br/>sources.py"]
        K[("🔐 Keychain<br/>iCal secret address")]
        LOG[["~/Library/Logs/<br/>lg-tv-briefing.log"]]
        L1 --> R
        L2 --> W
        R --> G
        W --> G
        G --> K
        R --> LOG
        W --> LOG
    end
    subgraph Net["☁️ Internet"]
        GC["Google Calendar"]
        OM["Open-Meteo"]
        RSS["The Hindu · BBC RSS"]
    end
    G --> GC & OM & RSS
    R -- "power on · busy check ·<br/>open browser · toast · auto-off" --> TV["📺 TV"]
    TV -- "GET / every 5 min<br/>(only the TV and this Mac allowed)" --> W

One scheduled run

sequenceDiagram
    autonumber
    participant L as launchd (07:30)
    participant R as briefing run
    participant TV as LG TV
    participant W as page server
    L->>R: start
    R->>R: gather calendar, weather, headlines
    alt TV off
        R->>TV: Wake-on-LAN / turnOn
    else TV busy (playing, Live TV, an app)
        R->>TV: toast "Morning briefing: …"
        Note over R,TV: done, screen left alone
    end
    R->>TV: launch browser → http://mac:8765/
    TV->>W: GET /
    R->>W: poll /api/views
    W-->>R: TV loaded the page ✓
    alt page never loads
        R->>TV: fallback toasts
    end
    R->>R: wait 30 min
    R->>TV: still showing the page? → power off

Project layout

lg-tv/
├── src/lgtv_mcp/
│   ├── server.py              # MCP server: 21 tools, error handling
│   ├── tv.py                  # connection, SSDP rediscovery, pairing, Wake-on-LAN, ensure_on()
│   ├── pair.py                # `lgtv-pair` CLI
│   └── briefing/
│       ├── cli.py             # `briefing now|run|serve|preview|install|uninstall|status`
│       ├── config.py          # briefing.toml, Keychain lookup, rotating log
│       ├── sources.py         # iCal (recurrence/timezones), Open-Meteo, RSS; each fails on its own
│       ├── page.py            # 1080p TV page (dark, large type, 5-min refresh, live clock)
│       ├── web.py             # aiohttp server with an IP allowlist
│       └── show.py            # busy check, browser launch + load confirmation, toasts, auto-off
└── scripts/
    └── install_claude_desktop.py

🔒 Privacy and security

Everything runs on your Mac and your home network. There is no cloud relay, and nothing listens on the internet.

  • Pairing key: ~/.config/lgtv/config.json (mode 0600). Anyone with this key on your network can control the TV, so treat it like a password. Delete it and run uv run lgtv-pair --force to re-pair; you can also remove the paired device on the TV.

  • Calendar: the Google Calendar secret iCal address stays in the macOS Keychain. It grants read access to your calendar without a login, so if it ever leaks, reset it in Google Calendar settings.

  • Briefing page: served on your LAN only, and the server answers just the TV, this Mac and any allow_ips you add. Don't port-forward it from your router.

  • What leaves the house: weather requests to Open-Meteo (your configured coordinates), RSS fetches to the feeds you list, and the calendar fetch to Google. Claude sees whatever its tools return, such as app lists and your calendar events in a briefing.

  • Not in this repo: your TV's IP and MAC, the pairing key, the calendar address and your briefing.toml. Keep it that way if you fork it.

🧪 Compatibility

Tested on one TV: an LG 55UT80406LA (UT80, 2024) on webOS 25 (10.3.2), controlled from a Mac mini on the same Wi-Fi.

  • Other LG TVs: aiowebostv speaks the same SSAP protocol across webOS versions, so other models will probably work. They're untested; app ids, deep links and the browser app can differ.

  • macOS only for the briefing: it relies on launchd, pmset and the Keychain. The MCP server itself is plain Python, but it's only been run on macOS.

  • Before pairing: turn on TV On With Mobile (needed for power_on) and, for faster wake-ups, Quick Start+. Exact menu paths vary by webOS version.

Issues are welcome. Please include your TV model, webOS version and the relevant lines from the log.

🩺 Troubleshooting

Symptom

Fix

A tool says the TV is off or unreachable while it's on

Check the Mac and the TV are on the same Wi-Fi. Run get_status again; it searches for the TV over SSDP if its IP changed

lgtv is missing from the desktop app's Connectors

Cmd+Q the app, run scripts/install_claude_desktop.py, then reopen

The briefing shows "Calendar unavailable"

uv run briefing status shows whether the Keychain item was found. The log gives the reason, e.g. an address Google has reset

The briefing came as toasts, not a page

Check briefing.server is running in uv run briefing status, and read the log for "never loaded"

Pairing prompt timed out

uv run lgtv-pair --force, then press OK on the TV within 60 s

Fixed IP (optional): reserve the TV's IP for its MAC address (both in ~/.config/lgtv/config.json) under DHCP reservation in your router's admin page.

🛠️ Development

uv run python -c "import asyncio; from lgtv_mcp.server import mcp; print([t.name for t in asyncio.run(mcp.list_tools())])"
uv run mcp dev src/lgtv_mcp/server.py      # MCP Inspector
uv run briefing preview                     # iterate on the TV page in a desktop browser

📄 License

MIT. LG and webOS are trademarks of LG Electronics. This project is not affiliated with or endorsed by LG.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Turns AI assistants like Claude and ChatGPT into a remote control for LG webOS smart TVs, enabling power control, volume, app launching, input switching, and more, all locally without cloud APIs.
      7
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      39
      15 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to control a Samsung Tizen smart TV on the local network directly over its local APIs, with no cloud account or hub required. Agents can check power and volume status, switch the TV on or off, send remote keys, type text, launch apps, and play YouTube videos, all under configurable volume and key-press guardrails.
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an AI agent to control an LG webOS TV by reading playback status, listing and launching apps, adjusting volume or mute, and powering it off.
      MIT