jellyfin-mcp

WIP

Jellyfin media server control.

GitHub repo → npm: jellyfin-mcp →

MCP tools

stdio

transport

MIT

license

WHAT IT DOES

jellyfin-mcp is a Model Context Protocol server for Jellyfin. Point an MCP-compatible client at it and your media server becomes a set of tools the agent can call: list who is watching what, pause a session, scan a library, run a scheduled task, message a client, or manage users, all as typed tool calls.

It exposes 56 tools across system info, libraries, users, sessions, items, scheduled tasks, user-data writes, playlists, collections, discovery, and Quick Connect. Destructive or privileged operations (restart, shutdown, delete_user, set_user_password, Quick Connect authorize, Continue Watching clears, bulk session controls, resume-position writes) require an explicit confirm: true.

Upstream Jellyfin error responses are summarized to status only before being returned to the model; the full body is logged to stderr for operators, so internal server detail is not surfaced to the assistant.

Status: work in progress. Published to npm as jellyfin-mcp (v0.4.0); expect the tool surface to keep shifting while it stabilizes.

INSTALL

Published to npm. Install globally to get the jellyfin-mcp binary, or build from source. Requires Node.js 20+ and a Jellyfin server with API access.

$ npm install -g jellyfin-mcp # install the server binary

# or from source

$ git clone https://github.com/solomonneas/jellyfin-mcp.git

$ cd jellyfin-mcp && npm install && npm run build

Configure with JELLYFIN_URL and JELLYFIN_API_KEY (Dashboard › API Keys). Optional: JELLYFIN_TIMEOUT (default 30s) and JELLYFIN_VERIFY_SSL (set false only for self-signed certs; the relaxed check is scoped to the Jellyfin connection alone).

CLIENT CONFIG

A sample mcpServers entry (Claude Desktop, or any MCP client that reads the same shape). It runs the installed binary over stdio.

{
  "mcpServers": {
    "jellyfin": {
      "command": "jellyfin-mcp",
      "env": {
        "JELLYFIN_URL": "http://localhost:8096",
        "JELLYFIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

For Claude Code use claude mcp add jellyfin --env JELLYFIN_URL=... --env JELLYFIN_API_KEY=... -- jellyfin-mcp. The README also documents OpenClaw, Codex CLI, and Hermes Agent, plus an SSH-tunnel recipe for a remote Jellyfin bound to localhost.

CAPABILITIES / TOOLS EXPOSED

56 MCP tools across system, libraries, sessions and playback, user data, items, playlists, collections, discovery, users, tasks, and Quick Connect. Grouped below; see the README for the full per-argument reference.

System & libraries

jellyfin_get_status

Server name, version, OS, pending restart, and update availability.

jellyfin_list_libraries / jellyfin_scan_library

List virtual folders with IDs and types; trigger a scan for one library or all.

jellyfin_restart_server / jellyfin_shutdown_server

Restart or stop the Jellyfin process (each requires confirm: true).

Sessions & playback

jellyfin_list_sessions

Active/idle clients with now-playing, progress, and paused state.

pause / resume / stop / seek / next / previous

Per-session transport control, plus volume, mute, audio-stream, and subtitle-stream.

jellyfin_play_on_session

Cast or remote-play items to a session (PlayNow / PlayNext / PlayLast).

send_message_to_session / *_all_sessions

Toast a client; bulk pause/stop/message matching sessions (bulk ops require confirm: true).

User data & discovery

mark_played / mark_unplayed / set_favorite

Per-user watched state and favorites.

continue-watching clears + preview

Preview a cleanup dry-run, then clear resume positions per item, per series, or all-but-latest (writes require confirm: true).

get_resume_items / get_next_up / get_similar_items

In-progress queue, next unwatched episode per series, and similar-item recommendations.

Items, playlists & collections

search_items / get_recent_items / get_item

Search by name, latest-added per user, and full metadata.

playlists: create / list / get / add / remove

Use the returned playlistEntryId for removal, not the raw item ID.

collections: create / add / remove

Build and curate Jellyfin collections.

Users, tasks & Quick Connect

list / create / delete / disable / set_password

User admin (delete and set_password require confirm: true).

list_scheduled_tasks / run_scheduled_task / get_activity_log

Inspect and run scheduled tasks; query recent server events.

quick_connect_status / quick_connect_authorize

Check Quick Connect and approve a pending login code (authorize requires confirm: true).

Note: jellyfin_set_user_password takes the new password as plaintext tool input, so it transits the LLM conversation and provider logs. Treat any password set this way as exposed: use a throwaway value or set passwords in the Jellyfin dashboard.