lgtv-mcp

MCP server (Python 3.12) to control an LG OLED C2 (webOS 22) over LAN.

Streamable HTTP transport (/mcp), required Bearer auth, public healthcheck at /healthz.

Prerequisites

• TV and host on the same LAN

• TV IP (LGTV_HOST) and MAC for Wake-on-LAN (LGTV_MAC)

• Python 3.12+ (local) or Docker

Related MCP server: lg-tv-mcp

Tools

• get_status - power, input/app, software info, paired

• get_settings - readable default keys; optional pic_mode+tv_input; per-key fallback

• set_picture_settings - allowlisted writes, auto backup before write

• set_picture_mode / set_input / power_on / power_off

• apply_preset - ps5 / switch2 (aliases ps5_hdr, ps5_sdr); variants sdr/hdr

• backup_settings / restore_settings / list_backups

• notify - on-screen toast

Presets draw from RTINGS C2, HDTVTest, and nintendolife Switch 2 HDR notes. Game Optimizer / console options stay manual (manual_steps).

Known limits

Live on LG OLED42C26LB (webOS 22, unsigned comp manifest):

• Refused picture keys (batch or single): gameOptimization, gameGenre, inputOptimization, vrr, allm, motionProOLED, localDimming, hdrMode, lowLevelAdjustment, whiteBalanceColorTemperature. truMotionMode has no value in game mode.

• software_info often returns 401 with the comp manifest; other status fields may still work.

• Settings writes work via set_settings / set_picture_settings (luna alert path) when pairing permissions allow.

• HDMI / tv_input ids vary per home (ps5 defaults to hdmi3, switch2 to hdmi2).

Config

Copy .env.example to .env and set at least MCP_BEARER_TOKEN (long random secret).

Pairing uses the unsigned manifest_comp.json (no signed certificate). Recent LG firmware blacklists the classic signed manifest.

Settings writes use the luna alert trick (createAlert/closeAlert). The comp manifest lacks WRITE_NOTIFICATION_ALERT and WRITE_SETTINGS. Constant EXTRA_PERMISSIONS in code is empty by default; set LGTV_EXTRA_PERMISSIONS=WRITE_NOTIFICATION_ALERT,WRITE_SETTINGS and re-pair with --force if picture/settings writes return insufficient permissions.

Never commit .env or the real token.

Docker deploy

cp .env.example .env   # then edit
mkdir -p data
docker compose up -d --build

network_mode: host reaches the TV and sends WOL on the LAN. Volume ./data:/data keeps the pairing key and backups.

Pairing

1. Power on the TV; same network as the host.

2. Run:

export $(grep -v '^#' .env | xargs)
python -m lgtv_mcp.pair

3. Accept the prompt on the TV (up to 90 s). Use --force to re-pair (required after changing LGTV_EXTRA_PERMISSIONS).

4. CLI prints redacted TV message summaries and paired (never the key).

5. Key is stored in $DATA_DIR/.aiopylgtv.sqlite.

Security notes

• Bearer auth is mandatory for /mcp; /healthz is public and does not touch the TV.

• Pairing key and token are secrets: keep them in DATA_DIR / .env, not in git.

• LAN-only: do not expose this server to the public internet without additional controls.

Local run / tests

python -m venv /tmp/lgtv-venv && source /tmp/lgtv-venv/bin/activate
pip install -e ".[dev]"
export $(grep -v '^#' .env | xargs)
python -m lgtv_mcp
pytest

Server: http://$MCP_BIND_HOST:$MCP_PORT/mcp. Tests mock the TV (no real network).

En bref

Serveur MCP pour piloter un LG OLED C2 en LAN (HTTP streamable, Bearer obligatoire). Configurer .env (LGTV_HOST=192.168.1.x, LGTV_MAC=AA:BB:CC:DD:EE:FF, MCP_BEARER_TOKEN), appairer avec python -m lgtv_mcp.pair, deployer via docker compose up -d --build.