samsung-tv-mcp

An MCP server that lets AI agents control a Samsung Tizen smart TV on your local network: power, volume, remote keys, text input, apps and YouTube videos.

You:    put lo-fi beats on the living room TV, not too loud
Claude: tv_status → standby
        tv_power {on: true}
        tv_play_youtube {video: "jfKfPfyJRdk"}
        tv_set_volume {level: 15}

It talks to the TV directly over its local APIs. No cloud account, no SmartThings, no hub.

Tools

Errors are returned as tool results (isError) with a stable code (not_paired, tv_off, bad_request) and a message the model can act on, rather than thrown, so the agent can recover by itself: pair, turn the TV on, or pick another app. The server also sends MCP instructions describing that flow.

Guardrails

An agent holding a TV remote should not be able to blast the volume at 3 a.m.

• tv_set_volume refuses levels above SAMSUNG_TV_MAX_VOLUME (default 50).

• tv_press_keys allows at most 5 volume_up per call, so the cap cannot be bypassed with keys, and at most 30 keys.

• KEY_POWER is not accepted as a key; power goes through tv_power, which checks the current state first, so "turn it on" never turns an already-on TV off.

• tv_status and tv_list_apps are annotated readOnlyHint, so clients can auto-approve them and ask before the rest.

Related MCP server: samsung-tv

Setup

Requires Node.js 20+ and a Samsung TV from 2016 or later on the same network.

git clone https://github.com/<you>/samsung-tv-mcp && cd samsung-tv-mcp
npm install
npx samsung-tv-mcp discover   # scans your /24 and remembers the TV
npx samsung-tv-mcp pair       # accept the pop-up on the TV with the physical remote
npx samsung-tv-mcp status

The IP, MAC and pairing token are stored in ~/.samsung-tv-mcp/.

Claude Code

claude mcp add samsung-tv -- node /path/to/samsung-tv-mcp/src/cli.mjs

Claude Desktop and other MCP clients

{
  "mcpServers": {
    "samsung-tv": {
      "command": "node",
      "args": ["/path/to/samsung-tv-mcp/src/cli.mjs"],
      "env": { "SAMSUNG_TV_MAX_VOLUME": "40" }
    }
  }
}

Configuration

How it talks to the TV

Things learned on a 2025 TV (UN43U8600F) that the older libraries and docs do not cover:

• The app list request is ignored. Newer TVs never answer ed.installedApp.get or ed.apps.launch over the WebSocket. They still answer GET /api/v2/applications/<id> one ID at a time, so the server probes a catalog of known IDs (src/apps.mjs) in parallel and keeps the ones the TV recognizes.

• DIAL needs a YouTube Origin. POST /ws/apps/YouTube answers 403 unless the request carries Origin: https://www.youtube.com.

• Volume over DLNA is absolute and token-free, which beats sending KEY_VOLUP twenty times.

• A TV that turns off does not close the WebSocket. The server drops the channel whenever the REST API stops answering, otherwise it would keep reporting "connected".

• Standby swallows Wake-on-LAN while the network stack is still up, so tv_power falls back to the power key.

• There is no API to install apps. None of the store IDs respond.

Tests

npm test

The suite runs a fake TV (test/fake-tv.mjs) that serves the same REST, DLNA, DIAL and WebSocket endpoints on one local port, including pairing approval, timeouts and revoked tokens. The MCP tests connect a real MCP client to the server over an in-memory transport, so they cover the protocol layer, not just the TV client.

Library use

import { SamsungTV } from 'samsung-tv-mcp';

const tv = new SamsungTV({ dataDir: './data', host: '192.168.1.50' });
await tv.pair();
await tv.launchApp('3201907018807'); // Netflix

License

MIT