MCP 服务器

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.

README

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