Jellyfin MCP Server
solomonneas/jellyfin-mcp
Controle Jellyfin por voz/IA com 56 ferramentas tipadas
Ver no GitHubServidor MCP que expõe a superfície de controle e gerenciamento do Jellyfin para LLMs através de tool calls tipados. Permite listar sessões ativas, controlar playback, gerenciar usuários e bibliotecas, executar tarefas agendadas e enviar mensagens — tudo via chamadas de função estruturadas.
Instalação
npx convez-ai solomonneas/jellyfin-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Controlar playback de sessões via comandos de IA
- Gerenciar usuários e permissões do servidor de mídia
- Monitorar quem está assistindo e quando
- Automatizar scans de biblioteca e tarefas agendadas
- Integrar Jellyfin com assistentes de IA
Veredito

Integração sólida e bem documentada entre Jellyfin e LLMs. A cobertura de 56 ferramentas (playback, usuários, bibliotecas, playlists) é abrangente; o requisito de `confirm: true` para operações destrutivas adiciona segurança. Ideal para automação de mídia em stacks que usam Claude.
README
A tradução para o português deste README ainda está na fila.
An MCP (Model Context Protocol) server for Jellyfin. Exposes Jellyfin's management and playback control surface to LLMs: list who's watching what, pause a session, scan a library, run a scheduled task, or message a client, all as typed tool calls.
Companion to arr-cli (the *arr stack CLI). arr-cli handles acquiring content; jellyfin-mcp handles serving, monitoring, and controlling playback.
Features
- 56 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_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 with Claude Desktop, Claude Code, OpenClaw, Hermes Agent, Codex CLI, and any MCP-compatible client
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_disabledjellyfin_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_sessionjellyfin_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
Collections
jellyfin_create_collectionjellyfin_add_to_collectionjellyfin_remove_from_collection
Items
jellyfin_search_items- by name, optional type filterjellyfin_get_recent_items- latest added (per-user)jellyfin_get_item- full metadata
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_taskjellyfin_get_activity_log
Install
npm install -g jellyfin-mcp
Or from source:
git clone https://github.com/solomonneas/jellyfin-mcp.git
cd jellyfin-mcp
npm install
npm run build
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.
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.
Development
npm install
npm run dev # watch mode with tsx
npm run typecheck # tsc --noEmit
npm run build # tsup bundle
npm test # vitest