TV Remote MCP
Controls Android TV / Google TV devices over ADB, supporting power, volume, navigation, app launch, input switching, and Wake-on-LAN.
Controls Google TV devices over ADB, supporting power, volume, navigation, app launch, input switching, and Wake-on-LAN.
Controls Panasonic Viera TVs via HTTP SOAP, supporting power, volume, navigation, app launch, input switching, and Wake-on-LAN.
Controls Roku TVs via HTTP ECP, supporting power, volume, navigation, app launch, input switching, and Wake-on-LAN.
Controls Samsung Tizen TVs via HTTP REST and WebSocket, supporting power, volume, navigation, app launch, input switching, and Wake-on-LAN.
Controls Sony Bravia TVs via HTTP REST/IRCC-over-HTTP, supporting power, volume, navigation, app launch, input switching, and Wake-on-LAN.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
šŗ TV Remote MCP
Control your smart TV from any phone or laptop browser over your local Wi-Fi ā with zero app store downloads, zero logins, and zero cloud tracking.
It also includes a local Model Context Protocol (MCP) server so your AI assistants (Claude, Cursor, Hermes, Antigravity, Gemini) can adjust volume, switch HDMI inputs, launch streaming apps, or turn off the TV when a task finishes.
š± Open Web Remote: projects.shivalgupta.me/tv-remote-mcp/remote/
š Project Home: projects.shivalgupta.me/tv-remote-mcp/ (Mirror: Shival-Gupta.github.io/tv-remote-mcp)
š Documentation: docs/
š¤ Using an AI assistant or coding agent?
Jump to AI Assistant & MCP Setup for one-command installation, MCP tool schemas, and agent skill integration.
ā” Quick Start
1. Open the Remote
Open projects.shivalgupta.me/tv-remote-mcp/remote/ on your phone (make sure you are connected to the same Wi-Fi network as your TV).
For Roku TVs: Works immediately from the browser without running any software on your computer.
For LG, Samsung, Android TV, Sony, or Vizio: Start the lightweight companion relay on your computer:
# Clone the repository
git clone https://github.com/Shival-Gupta/tv-remote-mcp.git
cd tv-remote-mcp
# Run the automated installer (installs dependencies & verifies setup)
python install.py
# Start the local relay
python server/relay.py2. Connect to Your TV
Tap Settings (ā) in the remote header, select your TV brand, and enter your TV's local IP address (e.g. 192.168.1.11).
If you're using the remote from your phone, enter your computer's local IP address as the relay server (e.g. http://192.168.1.12:7070). You can also open http://<YOUR_PC_IP>:7070/remote/ directly in your phone's browser.
Related MCP server: MCP Roku Control
šŗ Supported Brands & Technical Specs
Brand | Protocol | Default Port(s) | Auth / Pairing Method | Power On (Wake-on-LAN) |
LG WebOS (3.0+) | WebSocket ( |
| Click "Yes" on TV screen | ā UDP Magic Packet |
Samsung Tizen (2016+) | HTTP REST + WebSocket |
| Accept on-screen popup | ā UDP Magic Packet |
Roku TV | HTTP ECP |
| None (open REST) | ā ECP / Magic Packet |
Android TV / Google TV | ADB |
| Allow Network Debugging prompt | ā ADB Keyevent / WoL |
Fire TV | ADB |
| Allow Network Debugging prompt | ā ADB Keyevent / WoL |
Sony Bravia | HTTP REST / IRCC |
| Pre-Shared Key (PSK) or PIN | ā HTTP / Magic Packet |
Vizio SmartCast | HTTPS REST |
| On-screen 4-digit PIN | ā HTTPS / Magic Packet |
Philips (JointSpace) | HTTP REST |
| Digest Auth / PIN | ā HTTP / Magic Packet |
Panasonic Viera | HTTP SOAP |
| None / PIN | ā HTTP / Magic Packet |
TCL / Hisense | ADB or Roku ECP |
| Dependent on TV OS | ā Supported |
š ļø How It Works
āāāāāāāāāāāāāāāāāāāāāāāāāāā HTTP POST āāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Phone Web Remote UI ā āāāāāāāāāāāāāāāāāāāāāā¶ ā Local Relay Server ā
ā (Static GitHub Pages) ā ā (relay.py on Port 7070) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāā¬āāāāāāāāāāāāā
ā TV Native Protocol
ā (WebSocket / ADB / REST)
āāāāāāāāāāāāāāāāāāāāāāāāāāā MCP Tool Call āāāāāāāāāāāāāā¼āāāāāāāāāāāāā
ā AI Assistant Clients ā āāāāāāāāāāāāāāāāāāāāāā¶ ā Smart TV on LAN ā
ā (Claude / Cursor / AGY) ā ā (e.g. LG WebOS, Roku) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāāāāWhy the local relay exists: Web browsers running an HTTPS page cannot open direct TCP sockets or unencrypted HTTP connections to local network IPs due to CORS and mixed-content security rules. The lightweight Python relay (
server/relay.py) runs on your PC and acts as a transparent local bridge.Smart Power via Wake-on-LAN: When smart TVs are powered off, their operating systems enter low-power standby and shut down their network listening ports. TV Remote MCP uses a 5-packet UDP magic packet burst (broadcast + subnet broadcast + unicast) to wake the TV hardware over Wi-Fi/Ethernet.
Phone-first UI: Built with vanilla HTML5, CSS (Tailwind CDN), and JavaScript (<200KB total, no npm build step). It includes haptic feedback, D-pad angle mathematics, hold-to-repeat volume buttons, and offline caching via Service Worker.
š¤ AI Assistant & MCP Setup
TV Remote MCP provides a dedicated FastMCP server and Agent Skill so coding assistants and AI agents can interact with your TV using natural language:
"Turn down the volume by 5 steps and open YouTube on the TV."
"Switch the TV input to HDMI 2 for the console."
"Turn off the living room TV when this test suite finishes."
One-Command Automated Setup
From your terminal (or when asking an AI assistant to set up this repository), run:
python install.py(On Linux/macOS, ./install.sh also works).
What install.py does:
Installs dependencies from
requirements.txt(pywebostv,requests,websockets,fastmcp).Auto-detects and writes MCP configuration for:
Claude Desktop:
%APPDATA%\Claude\claude_desktop_config.json(Windows) /~/Library/Application Support/Claude/(macOS) /~/.config/Claude/(Linux).Cursor: Workspace configuration in
.cursor/mcp.json.
Registers the
smart-tv-controlskill into.agents/skills/,.claude/skills/, and machine-global agent directories (~/.gemini/config/skills/,~/.claude/skills/).Runs
tests/test_mcp_server.pyto confirm all 7 test cases pass.Scans your local network subnet and reports discovered smart TVs.
MCP Tools Reference
Tool Name | Arguments | Description |
|
| Executes a TV command (see Action list below) |
|
| Scans the local network subnet for active smart TVs |
| (none) | Returns the list of supported smart TV brand IDs |
Supported Actions
Power:
power_on(Wake-on-LAN),power_offVolume:
volume_up,volume_down,mute,volume_set(arg:0ā100)Navigation:
up,down,left,right,enter,back,homeMedia:
media_play,media_pause,media_stopApps:
launch_app(arg: app ID),list_appsInputs:
set_input(arg:HDMI_1,HDMI_2, etc.)
Direct CLI Control (No Server Daemon Required)
You can also send commands directly from your terminal or shell scripts:
# Discover TVs on your local Wi-Fi
python skills/smart-tv-control/scripts/tv_cli.py discover
# Wake up TV via Wake-on-LAN
python skills/smart-tv-control/scripts/tv_cli.py power_on 192.168.1.11
# Adjust volume or launch apps
python skills/smart-tv-control/scripts/tv_cli.py action 192.168.1.11 lg volume_up
python skills/smart-tv-control/scripts/tv_cli.py launch 192.168.1.11 lg youtube.leanback.v4Agent Instruction Files
For Claude Code & Hermes: Read
CLAUDE.mdFor Antigravity & Pair Programming: Read
AGENTS.mdComplete Skill Playbook: Read
skills/smart-tv-control/SKILL.md
š® Streaming App Identifiers
When launching apps via MCP or CLI, use these platform identifiers:
Service | LG WebOS ID | Roku App ID | Android TV / Fire TV Package |
YouTube |
|
|
|
Netflix |
|
|
|
Prime Video |
|
|
|
Disney+ |
|
|
|
Spotify |
|
|
|
Apple TV+ |
|
|
|
(See skills/smart-tv-control/references/app-ids.md for complete lookup table).
š Project Structure
tv-remote-mcp/
āāā install.py # Automated installer (dependencies + MCP config + skills + tests)
āāā install.sh # Unix/macOS shell installer wrapper
āāā requirements.txt # Python package dependencies
āāā CLAUDE.md # Claude Code & Hermes agent instructions
āāā AGENTS.md # Antigravity developer rules & brand reference
āāā index.html # Landing page (GitHub Pages root)
āāā manifest.json # Progressive Web App manifest
āāā sw.js # Service Worker (offline cache)
āāā remote/
ā āāā index.html # Universal Smart TV Web Remote application
āāā server/
ā āāā relay.py # Local relay server (browser ā TV bridge, port 7070)
ā āāā mcp-server.py # FastMCP server & HTTP RPC bridge (port 8000)
āāā skills/
ā āāā smart-tv-control/ # AI Agent Skill package
ā āāā SKILL.md # Procedural playbook with YAML frontmatter
ā āāā scripts/
ā ā āāā tv_cli.py # Standalone CLI helper (discover, action, power_on, launch)
ā āāā references/
ā āāā brand-protocols.md # Port, transport, and auth guide
ā āāā app-ids.md # Complete app IDs & HDMI input mappings
āāā tests/
ā āāā test_mcp_server.py # 7-step automated MCP server test suite
ā āāā test_lg_tv.py # 9-step physical hardware validation suite
āāā docs/ # Setup guides, pairing recipes, and troubleshooting
āāā assets/ # Shared CSS, JS, and SVG iconsš Privacy & Security
100% Local: All commands travel exclusively over your home Wi-Fi network. No cloud accounts, no third-party telemetry, and no external tracking.
Local Token Storage: Pairing tokens and TV MAC addresses are stored in
tv-tokens/tokens.jsonlocally on your machine.Git Protection:
tv-tokens/,*.token,*.key, and.envare strictly gitignored to prevent accidental credential commits.
š§Ŗ Testing & Validation
# Automated MCP Server Test Suite (7/7 tests PASS)
python tests/test_mcp_server.py
# Physical Hardware Validation (LG NanoCell 4K Nu88 ā 9/9 steps PASS)
python tests/test_lg_tv.pyā Frequently Asked Questions (FAQ)
š¤ Contributing
Contributions are welcome! Please review CONTRIBUTING.md for guidelines on code standards, phone-first responsive design, and atomic commits.
š License
This project is open source and licensed under the MIT License.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
This server cannot be deployed
Maintenance
Related MCP Connectors
Control Android TV from any AI. 38 MCP tools: playback, recap, recommend, smart-home, schedules.
Give your AI agent the power to cast to your home TV and control an interactive canvas. By ArdaBot.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Control your Tesla from your AI assistant - climate, charging, access, and security.
Related MCP Servers
- AlicenseBqualityAmaintenanceControl any smart TV with natural language ā play Netflix/YouTube/Spotify by name, cast URLs, scene presets, multi-room audio, and multi-TV sync. Supports LG, Samsung, Android TV, Roku.2373 PyPI58MIT
- FlicenseAqualityDmaintenanceEnables AI assistants to control Roku TVs on the local network via natural language commands.6-
- AlicenseBqualityDmaintenanceEnables AI assistants to discover and control IoT devices on local networks and via Bluetooth LE.71MIT
- FlicenseBqualityDmaintenanceEnables discovery and control of smart appliances (TVs, media devices) on the local network through natural language, supporting providers like Roku, Google TV, and Home Assistant.18-