jellyctrl MCP server
Commit Oct 22, 2026Lets an AI client manage Jellyfin media servers by inspecting libraries, controlling playback sessions, and managing users through schema-validated tools.
Also known as lidless-labs/jellyctrl
- Stars
- 4
- Tools
- 42
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 22, 2026
- License
- MIT
What is jellyctrl MCP?
jellyctrl lets an AI client manage Jellyfin media servers by inspecting libraries, controlling playback sessions, and managing users through schema-validated tools. It exposes 42 tools, such as jellyfin_get_status, jellyfin_restart_server, jellyfin_shutdown_server.
Summary generated from the project's README
About jellyctrl MCP server
jellyctrl provides a command-line interface and MCP server for managing Jellyfin media servers. It is designed for operators, developers, and AI agents who need to interact with self-hosted media libraries without using a web dashboard. The tool allows for inspecting libraries, managing user accounts, and controlling active playback sessions through a structured, typed interface.
Users can run the server locally via stdio or through an optional HTTP transport for remote clients. Setup requires a Jellyfin URL and an API key provided through environment variables. For added security, the HTTP transport uses a separate bearer token and supports different remote modes like observe, managed, or full to restrict tool permissions. The MCP implementation includes 57 schema-validated tools, many of which feature confirmation gates for destructive actions like deleting users or stopping sessions.
What you can do with it
- 1Monitor active playbackAsk an AI agent to identify what media is currently being watched in a specific room.
- 2Manage media librariesTrigger a library scan to update the media catalog via the command line.
- 3Control playback sessionsInstruct an agent to pause or resume a specific media stream.
Written from the project's README. Every use case is checked against a quote from it.
jellyctrl MCP tools 42
Detected from the READMEjellyfin_get_statusjellyfin_restart_serverjellyfin_shutdown_serverjellyfin_list_librariesjellyfin_scan_libraryjellyfin_list_usersjellyfin_create_userjellyfin_list_sessionsjellyfin_pause_sessionjellyfin_resume_sessionjellyfin_send_message_to_sessionjellyfin_seek_session
| jellyfin_get_status | — | |
| jellyfin_restart_server | — | |
| jellyfin_shutdown_server | — | |
| jellyfin_list_libraries | — | |
| jellyfin_scan_library | — | |
| jellyfin_list_users | — | |
| jellyfin_create_user | — | |
| jellyfin_list_sessions | — | |
| jellyfin_pause_session | — | |
| jellyfin_resume_session | — | |
| jellyfin_send_message_to_session | — | |
| jellyfin_seek_session | — |
Show all 42 toolsShow fewer tools
jellyfin_set_volumejellyfin_play_on_sessionjellyfin_pause_all_sessionsjellyfin_stop_all_sessionsjellyfin_message_all_active_sessionsjellyfin_preview_continue_watching_clearjellyfin_clear_continue_watchingjellyfin_clear_series_continue_watchingjellyfin_clear_episode_continue_watching_except_latestjellyfin_get_watch_historyjellyfin_get_user_item_datajellyfin_set_resume_positionjellyfin_list_playlistsjellyfin_create_playlistjellyfin_get_playlist_itemsjellyfin_add_to_playlistjellyfin_create_collectionjellyfin_add_to_collectionjellyfin_search_itemsjellyfin_get_recent_itemsjellyfin_get_itemjellyfin_get_favorite_itemsjellyfin_get_resume_itemsjellyfin_get_next_upjellyfin_get_similar_itemsjellyfin_quick_connect_statusjellyfin_quick_connect_authorizejellyfin_list_scheduled_tasksjellyfin_run_scheduled_taskjellyfin_get_activity_log
| jellyfin_set_volume | — | |
| jellyfin_play_on_session | — | |
| jellyfin_pause_all_sessions | — | |
| jellyfin_stop_all_sessions | — | |
| jellyfin_message_all_active_sessions | — | |
| jellyfin_preview_continue_watching_clear | — | |
| jellyfin_clear_continue_watching | — | |
| jellyfin_clear_series_continue_watching | — | |
| jellyfin_clear_episode_continue_watching_except_latest | — | |
| jellyfin_get_watch_history | — | |
| jellyfin_get_user_item_data | — | |
| jellyfin_set_resume_position | — | |
| jellyfin_list_playlists | — | |
| jellyfin_create_playlist | — | |
| jellyfin_get_playlist_items | — | |
| jellyfin_add_to_playlist | — | |
| jellyfin_create_collection | — | |
| jellyfin_add_to_collection | — | |
| jellyfin_search_items | — | |
| jellyfin_get_recent_items | — | |
| jellyfin_get_item | — | |
| jellyfin_get_favorite_items | — | |
| jellyfin_get_resume_items | — | |
| jellyfin_get_next_up | — | |
| jellyfin_get_similar_items | — | |
| jellyfin_quick_connect_status | — | |
| jellyfin_quick_connect_authorize | — | |
| jellyfin_list_scheduled_tasks | — | |
| jellyfin_run_scheduled_task | — | |
| jellyfin_get_activity_log | — |
Configuration
JELLYFIN_API_KEYJELLYFIN_MCP_HTTP_TOKENJELLYFIN_URL
| Name | Description | |
|---|---|---|
| JELLYFIN_API_KEY | — | |
| JELLYFIN_MCP_HTTP_TOKEN | — | |
| JELLYFIN_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelidless-labs/jellyctrl is public and reachablegithub.com/lidless-labs/jellyctrl ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-22github.com/lidless-labs/jellyctrl ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model42 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubjellyctrl is an operator control CLI for Jellyfin, the free self-hosted media server. It gives shells, cron, CI, and agents a typed command surface for inspecting and operating a Jellyfin server without clicking through the dashboard. The same npm package is still published as jellyfin-mcp for compatibility, and the MCP adapter remains available through both jellyctrl mcp and the legacy jellyfin-mcp bin.
You want it because asking "what's playing in the living room?" or running jellyctrl sessions --active-only is faster than dashboard hopping, and because an agent can chain those steps when launched through MCP. Compared with a generic HTTP tool or hand-written script, the MCP adapter exposes 57 schema-validated tools with confirm: true gates on every destructive operation and annotations that let clients route those calls to human approval.
Status: WIP. Used daily against a real Jellyfin server, but the tool surface is still settling and breaking changes can land between minor versions. Pin a released version if you need stability.
Companion to arr-cli (the *arr stack CLI). arr-cli handles acquiring content; jellyctrl handles serving, monitoring, and Jellyfin operations.
What it does
Jellyfin is a free, self-hosted media server: your movies, shows, music, and photos on hardware you control. jellyctrl puts that media server's management surface in front of operators first: list sessions, inspect libraries, query users, search items, review activity, and script routine checks from the command line.
For MCP-compatible clients, jellyctrl mcp exposes the same project as a stdio MCP server with 57 typed tools so an agent can list who is watching what, pause or cast a session, scan a library, manage users, prune Continue Watching, run a scheduled task, or message a client, all as structured tool calls instead of raw REST. The MCP surface is read-and-write: discovery and reporting tools are read-only, while every destructive or privileged operation is gated behind an explicit confirm: true flag and a destructiveHint annotation. The jellyfin-mcp command remains supported as a compatibility bin.
Install
npm install -g jellyfin-mcp
This installs jellyctrl, the compatibility jellyfin-mcp stdio MCP bin, and the optional jellyfin-mcp-http loopback HTTP bin.
Or from source:
git clone https://github.com/lidless-labs/jellyctrl.git
cd jellyctrl
npm install
npm run build
Quickstart
Set your Jellyfin connection details, then run a CLI command:
export JELLYFIN_URL=http://192.0.2.10:8096
export JELLYFIN_API_KEY=your-api-key-here
jellyctrl status
jellyctrl sessions --active-only
For MCP clients, start the adapter with jellyctrl mcp or keep using the compatibility jellyfin-mcp bin. No global install is required for the MCP path; npx fetches and runs the published jellyfin-mcp package:
{
"mcpServers": {
"jellyfin": {
"command": "npx",
"args": ["-y", "jellyfin-mcp"],
"env": {
"JELLYFIN_URL": "http://192.0.2.10:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}
}
}
}
Then ask your agent: "What's playing on Jellyfin right now?" It will call jellyfin_list_sessions and report back.
Optional local HTTP transport
The default MCP transport is stdio. Use jellyfin-mcp-http when an MCP client needs Streamable HTTP on the same machine, or through an authenticated proxy whose origin runs on that machine. The listener accepts MCP JSON-RPC only at POST /mcp, has a non-sensitive GET /healthz response, and binds to loopback only.
Set a separate bearer token. Do not reuse JELLYFIN_API_KEY for this token.
export JELLYFIN_URL=http://192.0.2.10:8096
export JELLYFIN_API_KEY=your-jellyfin-api-key
export JELLYFIN_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
jellyfin-mcp-http
The HTTP listener defaults to 127.0.0.1:3000. Its configuration is intentionally strict:
| Variable | Default | Purpose |
|---|---|---|
JELLYFIN_MCP_HTTP_HOST |
127.0.0.1 |
Loopback bind, only 127.0.0.1 or ::1. Wildcards are refused |
JELLYFIN_MCP_HTTP_PORT |
3000 |
TCP port, an integer from 1 to 65535 |
JELLYFIN_MCP_HTTP_TOKEN |
Required | Independent bearer token, at least 32 characters after trimming whitespace. Send as Authorization: Bearer <token> |
JELLYFIN_MCP_REMOTE_MODE |
observe |
Tool policy fixed at process startup, never changed by an MCP request |
Host and Origin checks run before /healthz and authentication. Host must identify a loopback alias or the bound host. Origin may be absent or an exact HTTP(S) loopback origin. Invalid headers receive 403 Forbidden.
Remote modes provide a second server-side control in addition to each tool's existing confirm: true requirement:
observepermits only read tools.managedalso permits routine media, library, session, and user-data writes.fullpermits every registered tool. High-impact tools still require their existingconfirm: trueargument.
In managed mode, the server denies restart, shutdown, account creation or deletion, password changes, account enable or disable, scheduled-task execution, session stop or stop-all, destructive playlist or collection removal, bulk resume clearing, and Quick Connect authorization. Unknown or unclassified tools are denied in every mode.
Do not expose this listener directly or change it to a non-loopback bind. For remote clients, keep the loopback origin and put an identity-aware proxy or tunnel in front of it. Keep the HTTP token as a second authentication layer, independent from the Jellyfin API key, and rotate it if a client or its logs may have exposed it.
Tools
System
jellyfin_get_status- server name, version, OS, pending restart, update availabilityjellyfin_restart_server- restart the Jellyfin process (requiresconfirm: true)jellyfin_shutdown_server- stop the Jellyfin process (requiresconfirm: true)
Libraries
jellyfin_list_libraries- all virtual folders with IDs, collection types, pathsjellyfin_scan_library- trigger scan for one library or all
Users
jellyfin_list_users- with admin / disabled flags and last login timestampsjellyfin_create_userjellyfin_delete_user(requiresconfirm: true)jellyfin_set_user_disabled(requiresconfirm: true)jellyfin_set_user_password(requiresconfirm: true)
Warning:
jellyfin_set_user_passwordtakes the new password as plaintext tool input. That means the password transits your LLM conversation, the model provider's request logs, and any saved session transcript. Treat any password set this way as exposed: use a throwaway value and have the user change it in the Jellyfin UI, or set passwords in the Jellyfin dashboard instead.
Sessions & Playback
jellyfin_list_sessions- active/idle clients with now-playing, progress, paused statejellyfin_pause_sessionjellyfin_resume_sessionjellyfin_stop_session(requiresconfirm: true)jellyfin_send_message_to_session- toast/dialog on the clientjellyfin_seek_session- jump to a position in secondsjellyfin_next_track/jellyfin_previous_trackjellyfin_set_volume(0-100) /jellyfin_set_mute(mute/unmute/toggle)jellyfin_set_audio_stream/jellyfin_set_subtitle_stream(use -1 to disable subtitles)jellyfin_play_on_session- cast/remote-play one or more items to a session (PlayNow / PlayNext / PlayLast)jellyfin_pause_all_sessions- pause matching sessions (requiresconfirm: true)jellyfin_stop_all_sessions- stop matching sessions (requiresconfirm: true)jellyfin_message_all_active_sessions- message matching active sessions (requiresconfirm: true)
User Data
jellyfin_mark_played/jellyfin_mark_unplayedjellyfin_set_favorite/jellyfin_unset_favoritejellyfin_preview_continue_watching_clear- dry-run a Continue Watching cleanup with optional filtersjellyfin_clear_continue_watching- clear resume positions for selected items or a filtered Continue Watching queue (requiresconfirm: true)jellyfin_clear_series_continue_watching- clear resume positions for one show's episodes (requiresconfirm: true)jellyfin_clear_episode_continue_watching_except_latest- keep one episode resume entry and clear older entries for a show (requiresconfirm: true)jellyfin_get_watch_history- recently watched items for a userjellyfin_get_user_item_data- raw watched/favorite/resume data for one itemjellyfin_set_resume_position- set a user's resume position for an item (requiresconfirm: true)
Playlists
jellyfin_list_playlistsjellyfin_create_playlistjellyfin_get_playlist_items- returnsplaylistEntryId(use this for removal, not the raw item ID)jellyfin_add_to_playlistjellyfin_remove_from_playlist(requiresconfirm: true)
Collections
jellyfin_create_collectionjellyfin_add_to_collectionjellyfin_remove_from_collection(requiresconfirm: true)
Items
jellyfin_search_items- by name, optional type filterjellyfin_get_recent_items- latest added (per-user)jellyfin_get_item- full metadata (requiresuserId)jellyfin_get_favorite_items- user's favorite items, with pagination
Discovery
jellyfin_get_resume_items- in-progress playback for a user, with resume position in secondsjellyfin_get_next_up- next unwatched episode per series for a user; optionalseriesIdfilterjellyfin_get_similar_items- Jellyfin's built-in "similar" recommendations for a given item
Quick Connect
jellyfin_quick_connect_status- whether Quick Connect is enabled on the serverjellyfin_quick_connect_authorize- approve a pending code for a user (requiresconfirm: true)
Tasks & Activity
jellyfin_list_scheduled_tasksjellyfin_run_scheduled_task(requiresconfirm: true)jellyfin_get_activity_log
CLI
jellyctrl is the primary operator interface for shells, cron, and CI. It shares the JellyfinClient core with the MCP adapter and reads the same env config. The current CLI exposes the read/report/lookup commands; playback control, user management, library scans, and other write operations stay in the MCP surface behind the confirm: true gates.
npx jellyfin-mcp@latest status
# or, installed globally:
jellyctrl status # server info; exit 1 if unreachable
jellyctrl libraries
jellyctrl users
jellyctrl sessions --active-only
jellyctrl search "blade runner" --type Movie --limit 5
jellyctrl item 6e0b... --user 3f1c... # full metadata for one item
jellyctrl recent --user 3f1c... --limit 10
jellyctrl resume --user 3f1c... # Continue Watching, with resume position
jellyctrl next-up --user 3f1c... --series 9a2d...
jellyctrl similar 6e0b... --user 3f1c...
jellyctrl history --user 3f1c... --type Movie,Episode
jellyctrl user-data --user 3f1c... --item 6e0b...
jellyctrl activity --limit 50
jellyctrl tasks
jellyctrl playlists --user 3f1c...
jellyctrl playlist 4c7e... --user 3f1c...
jellyctrl status --json # raw JSON for piping
Run jellyctrl help for the full command and flag list. --json emits raw JSON instead of the concise human-readable summary. The CLI reads JELLYFIN_URL, JELLYFIN_API_KEY, JELLYFIN_TIMEOUT, and JELLYFIN_VERIFY_SSL (see Configuration); for example:
export JELLYFIN_URL=http://192.0.2.10:8096
export JELLYFIN_API_KEY=your-api-key-here
jellyctrl status
Exit codes: 0 success, 1 runtime error (backend unreachable / call failed, and status when the server reports no version), 2 usage error (unknown command/flag or bad value).
Starting the MCP adapter
jellyctrl mcp starts the stdio MCP adapter. The compatibility jellyfin-mcp bin does the same thing and remains supported. Launchers that reference the file path dist/index.js directly keep working; new launchers can point at dist/mcp-bin.js (or dist/cli.js mcp). Launchers that use the jellyfin-mcp bin name need no change.
Configuration
Set these environment variables in your MCP client config:
| Variable | Required | Default | Description |
|---|---|---|---|
JELLYFIN_URL |
yes | none | Base URL, e.g. http://localhost:8096 or https://jellyfin.example.com |
JELLYFIN_API_KEY |
yes | none | API key from Jellyfin Dashboard > API Keys |
JELLYFIN_TIMEOUT |
no | 30 |
Request timeout in seconds |
JELLYFIN_VERIFY_SSL |
no | true |
Set to false to skip TLS certificate validation for the Jellyfin connection (e.g. self-signed certs) |
Note:
JELLYFIN_VERIFY_SSL=falseonly relaxes certificate validation for the Jellyfin connection itself (via a confined per-request HTTP dispatcher). It does not touch global TLS settings, so certificate validation for any other outbound request in the process is unaffected. Leave it at the secure default unless you specifically need it.
Getting an API key
- Log into Jellyfin as an admin
- Dashboard > API Keys >
+ - Name it (e.g.
mcp) and save - Copy the value
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"jellyfin": {
"command": "jellyfin-mcp",
"env": {
"JELLYFIN_URL": "http://localhost:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}
}
}
}
Claude Code
claude mcp add jellyfin \
--env JELLYFIN_URL=http://localhost:8096 \
--env JELLYFIN_API_KEY=your-api-key-here \
-- jellyfin-mcp
Add --scope user to make it available from any directory instead of only the current project.
OpenClaw
If you're running from a source checkout instead of the npm-installed binary, point command/args at the built dist/index.js:
openclaw mcp set jellyfin '{
"command": "node",
"args": ["/absolute/path/to/jellyfin-mcp/dist/index.js"],
"env": {
"JELLYFIN_URL": "http://localhost:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}
}'
Or, with the global npm install:
openclaw mcp set jellyfin '{
"command": "jellyfin-mcp",
"env": {
"JELLYFIN_URL": "http://localhost:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}
}'
Then restart the OpenClaw gateway so the new server is picked up:
systemctl --user restart openclaw-gateway
openclaw mcp list # confirm "jellyfin" is registered
Hermes Agent
Hermes Agent reads MCP config from ~/.hermes/config.yaml under the mcp_servers key. Add an entry:
mcp_servers:
jellyfin:
command: "jellyfin-mcp"
env:
JELLYFIN_URL: "http://localhost:8096"
JELLYFIN_API_KEY: "your-api-key-here"
Or, when running from a source checkout instead of the global npm install:
mcp_servers:
jellyfin:
command: "node"
args: ["/absolute/path/to/jellyfin-mcp/dist/index.js"]
env:
JELLYFIN_URL: "http://localhost:8096"
JELLYFIN_API_KEY: "your-api-key-here"
Then reload MCP from inside a Hermes session:
/reload-mcp
Codex CLI
Codex CLI registers MCP servers via codex mcp add:
codex mcp add jellyfin \
--env JELLYFIN_URL=http://localhost:8096 \
--env JELLYFIN_API_KEY=your-api-key-here \
-- jellyfin-mcp
Or, when running from a source checkout:
codex mcp add jellyfin \
--env JELLYFIN_URL=http://localhost:8096 \
--env JELLYFIN_API_KEY=your-api-key-here \
-- node /absolute/path/to/jellyfin-mcp/dist/index.js
Codex writes the entry to ~/.codex/config.toml under [mcp_servers.jellyfin]. Verify with:
codex mcp list
Remote Jellyfin via SSH tunnel
If Jellyfin binds to localhost on a remote host (common on Windows media servers), forward the port before starting your MCP client:
ssh -N -L 8096:localhost:8096 mediaserver
Then point JELLYFIN_URL at http://localhost:8096. The MCP itself has no SSH logic, it just talks HTTP.
Features
jellyctrlCLI for operator status, library, user, session, item, activity, task, playlist, history, and user-data checks- MCP adapter through
jellyctrl mcpand the compatibilityjellyfin-mcpbin - 57 MCP tools covering system info, libraries, users, sessions, items, scheduled tasks, user data writes, playlists, collections, discovery, and Quick Connect
- Playback control: pause / resume / stop / seek / next / previous / volume / mute / audio-stream / subtitle-stream / cast (remote-play) / send-message / bulk session controls
- User data writes: mark watched/unwatched, add/remove favorites, preview or clear Continue Watching resume positions, set resume position
- Playlists: create, list, append, remove entries
- Collections: create, add, remove
- Discovery: resume queue, next-up episodes, similar items
- Quick Connect: check status, authorize a pending code for a user
- Library scan triggering (per-library or all)
- User admin: list, create, delete, enable/disable, reset password
- Activity log queries for recent events
- Destructive / privileged ops (
restart,shutdown,delete_user,set_user_password,quick_connect_authorize,jellyfin_run_scheduled_task,jellyfin_clear_continue_watching, bulk session controls, resume-position writes) require explicitconfirm: true - Upstream Jellyfin error responses are summarized (status only) before being returned to the client; the full response body is logged to stderr for operators, so internal server detail is not surfaced to the model
- Works from a shell, cron, CI, Claude Desktop, Claude Code, OpenClaw, Hermes Agent, Codex CLI, and any MCP-compatible client
Example Prompts
What's actively playing on Jellyfin right now?
Calls jellyfin_list_sessions with activeOnly=true.
Pause whatever's playing in the living room
Calls jellyfin_list_sessions, finds the session by device name, then jellyfin_pause_session.
Scan the Movies library
Calls jellyfin_list_libraries to find the ID, then jellyfin_scan_library.
Send a message to my partner's Jellyfin that dinner is ready
jellyfin_list_sessions -> pick by username -> jellyfin_send_message_to_session.
What scheduled tasks have failed recently?
jellyfin_list_scheduled_tasks and filter by lastStatus.
What was I watching last night?
Calls jellyfin_get_resume_items with the user's ID. Returns in-progress episodes/movies with resume position in seconds.
Clear my Continue Watching list for this user.
Calls jellyfin_list_users to resolve the target user, then jellyfin_clear_continue_watching with userId and confirm: true.
Show what would be cleared from Continue Watching for this show.
Calls jellyfin_preview_continue_watching_clear with seriesId before making changes.
I opened a bunch of episodes in one show. Keep the latest and clear the rest.
Calls jellyfin_clear_episode_continue_watching_except_latest with seriesId, userId, and confirm: true.
Set this movie to resume at 42 minutes.
Calls jellyfin_set_resume_position with positionSec=2520 and confirm: true.
What's the next episode of this show for me?
Calls jellyfin_get_next_up with the user's ID, optionally narrowed with seriesId.
Approve my phone's Jellyfin login. The code is
ABCDEF.
Calls jellyfin_list_users to resolve the target user, then jellyfin_quick_connect_authorize with code, userId, and confirm: true.
Why not alternatives?
- Why not just call the Jellyfin REST API from a generic HTTP tool? You can, but then the caller has to know the endpoint shapes, build query strings, and handle pagination and IDs by hand on every call. jellyctrl wraps useful read and reporting operations as stable CLI commands, and its MCP adapter exposes 57 named, schema-validated tools with descriptions, so a model picks
jellyfin_pause_sessioninstead of guessing atPOST /Sessions/{id}/Playing/Pause. It also redacts upstream error bodies and Quick Connect codes before they reach the model. - Why not a shell script or a few curl aliases? A script works for one fixed task. jellyctrl gives operators a reusable command surface, while the MCP adapter lets an agent compose steps it was not pre-programmed for ("find the living room session, see what's playing, pause it, then message my partner") and reuse the same tools across Claude Desktop, Claude Code, Codex CLI, OpenClaw, and any other MCP client.
- Why not the Jellyfin web dashboard? The dashboard is for a human clicking. jellyctrl is for operators and agents acting through commands, natural language, and larger workflows alongside other tools.
What jellyctrl is not
- Not a Jellyfin client or player. It does not stream, transcode, or render media. It controls and queries an existing Jellyfin server over HTTP; playback happens on your real Jellyfin clients.
- Not a content acquisition tool. Downloading, importing, or organizing files is out of scope. Pair it with arr-cli for the acquisition side.
- Not a security boundary on its own. The
confirm: truegates and MCPdestructiveHintannotations help clients route risky calls to human approval, but anyone who can reach this server with a validJELLYFIN_API_KEYcan act as that key allows. Scope the API key and keepJELLYFIN_VERIFY_SSLat its secure default. - Not a hosted service. There is no SaaS, no telemetry, and no network egress beyond the calls to the Jellyfin server you configure. It runs locally as a stdio MCP server.
Development
npm install
npm run dev # watch mode with tsx
npm run typecheck # tsc --noEmit
npm run build # tsup bundle
npm test # vitest
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for how the tools are structured and what lands easily, SECURITY.md for reporting vulnerabilities privately, and CODE_OF_CONDUCT.md for the ground rules.
jellyctrl MCP questions
What tools does jellyctrl MCP provide?
It exposes 42 tools, including jellyfin_get_status, jellyfin_restart_server, jellyfin_shutdown_server, jellyfin_list_libraries, jellyfin_scan_library.
How do I install jellyctrl?
You can install it globally using npm via npm install -g jellyfin-mcp or run it directly using npx.
Is it safe to perform destructive operations through the MCP server?
Yes, every destructive or privileged operation is gated behind an explicit confirm: true flag and a destructiveHint annotation to allow for human approval.
Can I use jellyctrl over HTTP instead of stdio?
Yes, you can use the optional jellyfin-mcp-http loopback HTTP bin if your MCP client requires a Streamable HTTP transport.
What are the different remote modes for the HTTP listener?
There are three modes: 'observe' (read-only), 'managed' (routine writes but no high-impact tasks), and 'full' (all tools permitted).