jellyctrl

Active

Operating a Jellyfin server means dashboard-hopping: click into Sessions to see who is watching, click into another pane to pause a stream, click again to scan a library. jellyctrl hands your agent a typed control surface over stdio so "pause whatever is playing in the living room" or "scan the Movies library" becomes one tool call, with every destructive action gated behind explicit confirmation.

GitHub repo → npm →
$npm i -g jellyfin-mcp
read + writeconfirm-gated writesstdioNode 20+

See it workrepresentative session

you
What is playing on Jellyfin right now, and pause whatever is on in the living room.
tool
jellyfin_list_sessions{ activeOnly: true }
result
2 active Living Room TV Blade Runner 2049 01:12:40 / 02:43:00 playing 192.0.2.24 Office Laptop The Expanse S3E5 00:18:02 / 00:52:11 playing 192.0.2.31
tool
jellyfin_pause_session{ sessionId: "a4f1c9" }
result
ok Living Room TV paused at 01:12:40
agent
Living Room TV was on Blade Runner 2049 at 1:12:40. Paused it. The Office Laptop is still playing The Expanse; leaving that one alone.

Representative session. Illustrative values, RFC 5737 addresses. Destructive and bulk actions require confirm: true; the tool talks HTTP to your server only.

What it does

Point any MCP client at jellyctrl (published to npm as jellyfin-mcp) and your Jellyfin media server becomes tools an agent can call: list active sessions, pause or cast a stream, scan a library, prune Continue Watching, run a scheduled task, or manage users, all as schema-validated tool calls instead of raw REST or dashboard clicks. It exists because inspecting and operating a running media server from a shell, cron, CI, or an agent is faster than clicking through the web UI, and because an agent can chain those steps end to end. Unlike a generic HTTP tool or a hand-written script, jellyctrl exposes 56 typed tools split into read-only discovery and reporting versus write operations, with every destructive or privileged call gated behind a confirm: true flag and a destructiveHint annotation so clients can route it to human approval. The same core also ships a jellyctrl CLI for the read and report commands, so shells and cron share one config with the MCP surface.

Capabilities56 tools across the server

System & libraries

5 tools

Server status and update check; list virtual folders; trigger a scan; restart or shutdown (confirm-gated).

Sessions & playback

18 tools

List active clients; pause, resume, stop, seek, skip, volume, mute, audio and subtitle streams, cast, and bulk controls.

User data & discovery

11 tools

Mark played, favorites, watch history, resume queue, next-up per series, similar items, and Continue Watching clears.

Items, playlists & collections

11 tools

Search and fetch item metadata; create, list, and edit playlists and collections.

Users & Quick Connect

7 tools

List, create, delete, disable, and reset users; check and authorize Quick Connect login codes.

Tasks & activity

3 tools

List and run scheduled tasks; query the recent server activity log.

Full tool reference on GitHub →

Setup

01 · install
npm i -g jellyfin-mcp
02 · configure

Configure with JELLYFIN_URL and JELLYFIN_API_KEY (Dashboard > API Keys). Optional: JELLYFIN_TIMEOUT (default 30s), JELLYFIN_VERIFY_SSL.

03 · mcp client config
{ "mcpServers": { "jellyfin": { "command": "npx", "args": ["-y", "jellyfin-mcp"], "env": { "JELLYFIN_URL": "http://192.0.2.10:8096", "JELLYFIN_API_KEY": "your-api-key-here" } } } }

Safety

how it stays safe
Discovery and reporting tools are read-only; every destructive or privileged operation (restart, shutdown, delete_user, set_user_password, Quick Connect authorize, Continue Watching clears, bulk session controls, resume-position writes) requires an explicit confirm: true flag plus a destructiveHint annotation, so clients can route it to human approval. Upstream Jellyfin error responses are summarized to status only before returning to the model; the full body is logged to stderr for operators, so internal server detail is not surfaced to the agent.

More in Homelab5 tools

proxmox-mcpOperate Proxmox VMs, containers, and nodes from your agent, every write gated. adguardctrlRun AdGuard Home DNS filtering from shells and agents, destructive writes gated. proxguardAudit Proxmox against CIS benchmarks: config parsers and remediation scripts. immichctrlOne typed control surface for Immich: search, albums, and duplicate audits. samba-ad-migrationAutomated migration of a Windows AD file share to Samba on Proxmox, with Winbind domain join and permission-preserving data copy.