Skip to main content
Glama

šŸ“ŗ TV Remote MCP

License: MIT Python: 3.8+ Protocol: FastMCP Platforms: 10+ Brands Tests: 7/7 Passing Zero Cloud

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.

šŸ¤– 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.py

2. 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 (wss:// / ws://)

3001 (SSL) / 3000

Click "Yes" on TV screen

āœ… UDP Magic Packet

Samsung Tizen (2016+)

HTTP REST + WebSocket

8001 / 8002

Accept on-screen popup

āœ… UDP Magic Packet

Roku TV

HTTP ECP

8060

None (open REST)

āœ… ECP / Magic Packet

Android TV / Google TV

ADB

5555

Allow Network Debugging prompt

āœ… ADB Keyevent / WoL

Fire TV

ADB

5555

Allow Network Debugging prompt

āœ… ADB Keyevent / WoL

Sony Bravia

HTTP REST / IRCC

80

Pre-Shared Key (PSK) or PIN

āœ… HTTP / Magic Packet

Vizio SmartCast

HTTPS REST

7345 / 9000

On-screen 4-digit PIN

āœ… HTTPS / Magic Packet

Philips (JointSpace)

HTTP REST

1925 / 1926

Digest Auth / PIN

āœ… HTTP / Magic Packet

Panasonic Viera

HTTP SOAP

55000

None / PIN

āœ… HTTP / Magic Packet

TCL / Hisense

ADB or Roku ECP

5555 / 8060

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)   │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜                        ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
  1. 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.

  2. 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.

  3. 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-control skill into .agents/skills/, .claude/skills/, and machine-global agent directories (~/.gemini/config/skills/, ~/.claude/skills/).

  • Runs tests/test_mcp_server.py to confirm all 7 test cases pass.

  • Scans your local network subnet and reports discovered smart TVs.

MCP Tools Reference

Tool Name

Arguments

Description

universal_action

host, brand, action, arg

Executes a TV command (see Action list below)

discover

network (optional)

Scans the local network subnet for active smart TVs

list_brands

(none)

Returns the list of supported smart TV brand IDs

Supported Actions

  • Power: power_on (Wake-on-LAN), power_off

  • Volume: volume_up, volume_down, mute, volume_set (arg: 0–100)

  • Navigation: up, down, left, right, enter, back, home

  • Media: media_play, media_pause, media_stop

  • Apps: launch_app (arg: app ID), list_apps

  • Inputs: 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.v4

Agent Instruction Files


šŸŽ® 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

youtube.leanback.v4

837

com.google.android.youtube.tv

Netflix

netflix

12

com.netflix.ninja

Prime Video

amazon

13

com.amazon.amazonvideo.livingroom

Disney+

com.disney.disneyplus-prod

291097

com.disney.disneyplus

Spotify

spotify-beehive

22271

com.spotify.tv.android

Apple TV+

com.apple.appletv

551012

com.apple.atve.androidtv.appletv

(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.json locally on your machine.

  • Git Protection: tv-tokens/, *.token, *.key, and .env are 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…

    Related MCP Connectors

    Related MCP Servers