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

Ask, "What new episodes can I watch?"
Choose one episode or arrange several shows into a queue.
The assistant finds a compatible source and starts it on the Samsung TV.
Playback progress is monitored while you watch.
If you stop early, your position is saved. If you finish, your watch state is updated.
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

Samsung remains the universal fallback and keeps its native power, volume, app-launch, DLNA playback, and telemetry controls. Saved Google Cast receivers such as Cellcom Master Boxes can also be selected explicitly or assigned as the default for one network fingerprint.

Target precedence is:

An explicit target on a Stremio playback request.
The saved target for the current network fingerprint.
Samsung.

Network mappings and receiver identities live in the local state directory as media-devices.json; they are not committed to the project.

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

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

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

Connect Spotify

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

Connect Trakt (optional)

Create a Trakt API application.
Fill %USERPROFILE%\.samsung-spotify-tv\trakt-credentials.json.
Call integration_auth with provider: "trakt" and action: "start".
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 Cast to TV choices inside Stremio. The automatic choice uses the current network mapping and then falls back to Samsung; named Samsung and Google Cast targets are also listed explicitly.

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.

Version 0.2.1 exposes nine domain-oriented tools:

Tool	Actions or scope
`media_status`	`all`, `config`, `integrations`, `tv`, `media_targets`, `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`

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 control plus network-aware routing to explicitly saved Google Cast receivers
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.

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.