Samsung TV MCP Server

A Model Context Protocol server that lets AI assistants control Samsung Smart TVs (Tizen OS, 2016+) over the local network. No cloud, no SmartThings account required.

Early release — Core functionality works and has been tested on a Samsung UN65TU7000 (2020, Tizen). Not all tools have been exhaustively tested across different TV models and firmware versions. Bug reports and PRs are welcome.

Features

• 18 tools for complete TV control via natural language
• Auto-discovery — finds Samsung TVs on your network via SSDP
• Zero config — no API keys, no cloud, everything runs locally
• Multi-protocol — combines WebSocket, REST, UPnP/DLNA, and Wake-on-LAN
• Persistent auth — first connection requires TV approval, then uses saved token
• Auto-reconnect — recovers from dropped WebSocket connections

Tools

Tool	Description
tv_discover	Scan LAN for Samsung Smart TVs
tv_info	Get TV status (model, IP, power, volume)
tv_power	Turn TV on (WoL) or off
tv_key	Send any remote control key press
tv_keys	Send a sequence of key presses
tv_navigate	Semantic navigation (home, back, source, menu...)
tv_volume	Get/set volume (0-100), mute/unmute
tv_channel	Change channel by number or up/down
tv_apps	List all installed apps
tv_launch	Launch app by name ("netflix") or ID
tv_close_app	Close a running app
tv_current_app	Detect which app is currently running
tv_aspect_ratio	Get/set aspect ratio (Default, 16:9, Zoom, 4:3)
tv_captions	Get caption state or toggle subtitles
tv_browser	Open a URL in the TV's browser
tv_text	Type text into active input fields
tv_cursor	Move virtual cursor on screen
tv_media	Play media via DLNA (video/audio/images) with transport controls

Requirements

• Python 3.10+
• Samsung Smart TV with Tizen OS (2016 or newer)
• TV and MCP server on the same local network

Installation

pip install "samsungtvws[encrypted]" "mcp[cli]"

Claude Code

claude mcp add samsung-tv -- python /path/to/samsung-tv-mcp/main.py

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "samsung-tv": {
      "command": "python",
      "args": ["/path/to/samsung-tv-mcp/main.py"]
    }
  }
}

First Connection

On the first WebSocket connection, the TV will show a popup asking to allow "ClaudeCode". Accept it once — a token is saved to token.json for future sessions.

To minimize prompts, go to Settings > General > External Device Manager > Device Connection Manager and set Access Notification to "First Time Only".

Supported App Aliases

You can use friendly names instead of numeric IDs:

netflix, youtube, prime, disney, spotify, apple tv, hbo, max, plex, browser, steam link, twitch, tiktok, tubi, pluto, paramount, gallery, smartthings

Architecture

main.py  →  FastMCP tools (thin layer, ~120 lines)
tv.py    →  SamsungTV client (WebSocket + UPnP + SSDP + WoL, ~250 lines)

• WebSocket (port 8002/8001): remote keys, apps, browser, text input, cursor
• REST (port 8001): device info, app launch/close
• UPnP SOAP (port 9197): precise volume control, DLNA media playback
• Wake-on-LAN: power on from standby

Known Limitations

• Wake-on-LAN may not work reliably on all models (requires TV config)
• No direct HDMI source switching via API (must navigate the source menu with keys)
• No brightness/contrast/picture settings control
• No screenshot capability
• Text input only works when the TV's virtual keyboard is active
• DRM-protected content cannot be streamed via DLNA

Tested On

• Samsung UN65TU7000KXZL (2020, Crystal UHD, Tizen, Colombia)

License

MIT