Samsung Stremio Spotify MCP

Your personal viewing assistant for Samsung TV

Tell it what you want to watch. It finds the right episode, starts it on your TV, remembers where you stopped, and keeps your evening moving.

You can ask naturally:

"What new episodes can I watch?"

"Continue the show I was watching."

"Build me a queue with these three episodes, in this order."

"Stop after this episode."

The project brings your Stremio library, Samsung TV, Spotify, and optional Trakt history into one conversation. You decide what you feel like watching or hearing; the assistant takes care of the steps around it.

What it changes about watching TV

Sit down and continue

You do not need to remember the season, episode, or timestamp. Ask to continue a show and the assistant can resume a partially watched episode or suggest the next unwatched one.

Know what is actually ready to watch

Ask what is new and get released, unwatched episodes from your own library that currently have a playable source. The answer is about what you can watch now, not just what appeared on a release calendar.

Plan an entire evening in one sentence

Create a manually ordered queue from different shows. Choose what plays first, what follows, and where the evening ends. The queue is saved locally and advances as episodes finish.

Let a binge flow naturally

When you explicitly ask to binge a show, the next unwatched episode can begin automatically. If you say "stop after this episode" or turn off the TV, the assistant respects that boundary.

Get a good stream without studying release names

The assistant considers availability, quality, file size, video and audio compatibility, seed health, language, and subtitle hints. It validates the selected source and can try another candidate when one fails.

Keep your viewing history useful

Real playback progress from the TV is saved back to Stremio. Partial episodes can be resumed later, and completed episodes are marked watched at the normal completion threshold. Trakt scrobbling can be added without making it a requirement for playback.

Control the rest of the room

The same conversation can open Spotify on the TV, find music, build an artist queue without interrupting the current song, control playback, or set the TV volume.

A typical evening

1. Ask, "What new episodes can I watch?"
2. Choose one episode or arrange several shows into a queue.
3. The assistant finds a compatible source and starts it on the Samsung TV.
4. Playback progress is monitored while you watch.
5. If you stop early, your position is saved. If you finish, your watch state is updated.
6. In binge or queue mode, the evening continues according to the order you chose.

Things you can ask

• Play season [season] episode [episode] of [show].
• Continue the show I was watching.
• Binge this show.
• Stop after this episode.
• Create a queue with these episodes, in this order.
• Skip this queue item.
• What new episodes can I watch?
• Mark the episode I just finished as watched.
• Play songs by [artist] without interrupting the current song.
• Set the TV volume to [level].

Built around your choices

The integrations are independent:

• Use Stremio without Spotify or Trakt.
• Use Spotify without connecting Stremio.
• Add Trakt only if you want scrobbling.
• Use TV controls without configuring a media account.

Credentials, playback state, queues, and pairing information stay on your computer. The HTTP service and local Stremio addon listen only on the local machine.

Current support

The current release is designed for Samsung smart TVs on the same local network. It uses Samsung-native control and the TV's media playback capabilities. The viewing, queue, library, and stream-selection layers are separated from the TV implementation so support for additional TV platforms can be added later.

Spotify and Trakt are optional. Stremio playback requires a linked Stremio account, suitable stream addons, and a reachable Samsung TV.

<details> <summary><strong>Installation and configuration</strong></summary>

Requirements

• Node.js 20 or newer
• A Samsung smart TV reachable from the same local network
• A working local SamsungTVControl installation for pairing, power, and remote keys
• Stremio with the desired stream addons installed
• A Spotify Developer application for Spotify features
• A Trakt API application for optional scrobbling

Install

git clone https://github.com/dudibuilds/samsung-stremio-spotify-mcp.git
cd samsung-stremio-spotify-mcp
npm install
npm run init-config

Local credentials and state are created under:

%USERPROFILE%\.samsung-spotify-tv\

The legacy directory name is retained so existing installations continue working.

Connect an MCP client

The server uses stdio by default. Point the MCP client to the absolute path of server/index.mjs:

{
  "mcpServers": {
    "samsung-stremio-spotify": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\samsung-stremio-spotify-mcp\\server\\index.mjs"
      ]
    }
  }
}

Restart the MCP client after changing its configuration.

Link Stremio

1. Call integration_auth with provider: "stremio" and action: "start".
2. Open and approve the returned link.
3. Call integration_auth with provider: "stremio" and action: "complete".

Connect Spotify

1. Create a Spotify Developer application.
2. Add http://127.0.0.1:18765/callback as a redirect URI.
3. Fill %USERPROFILE%\.samsung-spotify-tv\spotify-credentials.json.
4. Run npm run auth.

Connect Trakt (optional)

1. Create a Trakt API application.
2. Fill %USERPROFILE%\.samsung-spotify-tv\trakt-credentials.json.
3. Call integration_auth with provider: "trakt" and action: "start".
4. Approve the displayed code, then use action: "complete".

Run the optional HTTP service

npm run mcp:http

The MCP endpoint is http://127.0.0.1:4512/mcp.

Install the local Cast to TV addon

With the HTTP service running, install this URL in desktop Stremio:

http://127.0.0.1:4512/stremio-cast/manifest.json

This adds a Cast to Samsung TV option inside Stremio using the same source-selection and playback flow.

Environment overrides

See .env.example for optional path, device-name, Stremio server, host, and port overrides. Never place real credentials in .env.example or commit a populated environment file.

</details>

<details> <summary><strong>MCP tool reference</strong></summary>

Version 0.2.0 exposes nine domain-oriented tools:

Tool	Actions or scope
media_status	all, config, integrations, tv, stremio_playback
integration_auth	Provider-routed status, start, complete
tv_control	power_on, power_off, volume_adjust, volume_set, volume_zero, mute_toggle
spotify_discover	devices, search
spotify_playback	open, play, queue_artist, pause, resume, next, previous, set_volume
stremio_discover	search, library, new_episodes
stremio_library	add, remove, set_notifications, mark_watched
stremio_playback	play, pause, resume, stop, seek, enable_binge, disable_binge
stremio_queue	set, start, status, clear, skip

Each action validates only the parameters relevant to that action. Errors contain tool, action, code, and message.

Version 0.2 migration

Version 0.2 is a hard tool-API cutover. stremio_queue keeps its name and contract. stremio_library keeps its name but now requires a mutation action; library listing moved to stremio_discover. Other 0.1 tool names are no longer advertised or accepted.

Previous tools	Replacement
Configuration, TV status, provider status, playback status	media_status
Stremio, Spotify, and Trakt authentication status/actions	integration_auth
TV power, volume, and mute tools	tv_control
Spotify device and search tools	spotify_discover
Spotify playback and queue tools	spotify_playback
Stremio search, library listing, and new episodes	stremio_discover
Stremio library mutations and watched state	stremio_library
Stremio play and transport controls	stremio_playback

</details>

<details> <summary><strong>Technical notes and validation</strong></summary>

Playback behavior

• Explicit season and episode requests play immediately.
• Bare series titles propose resuming or starting the next unwatched episode.
• Playback is marked watched at 90% completion.
• Queue state and partial progress are persisted locally.
• Turning off the TV finalizes the session and stops automatic advancement.
• Failed sources allow the next ranked candidate to be attempted.

Main components

Area	Responsibility
Stremio core	Metadata, library state, watched bitfields, source discovery, ranking, and validation
Playback orchestrator	Sessions, progress, watched updates, binge mode, and queues
TV adapter	Samsung status, power, volume, app launch, casting, and playback telemetry
Spotify integration	Authentication, discovery, Connect playback, and artist queues
Playback observers	Optional integrations such as Trakt scrobbling
MCP registry	Nine tool schemas, action validation, and routing

Validation

npm run smoke
npm run mcp:smoke
npm audit --omit=dev

Tests use temporary state and block live TV and external network access.

</details>

Security

This software controls a physical television and uses authenticated media accounts. Keep credentials, pairing tokens, runtime state, and logs out of Git. Do not expose the HTTP MCP or local addon to the LAN or internet. See SECURITY.md.

License

MIT. See LICENSE.