Jellyfin MCP
FrankBurmo/jellyfin-mcp
Gerencie sua biblioteca Jellyfin conversando com Copilot
Ver no GitHubServidor MCP que integra Jellyfin com GitHub Copilot para gerenciar bibliotecas de mídia via linguagem natural. Analisa duplicatas, corrige divisões de CD, identifica arquivos sem metadados e reorganiza a biblioteca automaticamente.
Instalação
npx convez-ai FrankBurmo/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
- Eliminar versões duplicadas de filmes e séries
- Corrigir estrutura de séries com divisões incorretas
- Encontrar e processar arquivos sem identificação TMDB/IMDB
- Consolidar múltiplas qualidades (2160p, 1080p, SD) em um único ponto de entrada
Veredito

Solução técnica bem construída para quem mantém Jellyfin em produção. Requer conhecimento de configuração de ambiente e API, mas automatiza tarefas críticas de gestão de biblioteca que são tediosas manualmente. Vale para homelabs sérios.
README
A tradução para o português deste README ainda está na fila.
jellyfin-mcp
MCP (Model Context Protocol) server for Jellyfin media library management. Lets you ask GitHub Copilot to analyze duplicates, fix CD-splits, find unidentified files, and reorganize your library — all via natural language.
Tools
| Tool | Description |
|---|---|
get_stats | Quick health overview: total counts, missing metadata, duplicate groups |
find_missing_metadata | Find movies/series missing TMDB and/or IMDB identifiers |
analyze_duplicates | Group by TMDB ID, classify quality per version (2160p/1080p/SD, Bluray/WEB/DVD) |
find_cd_splits | Find CD-split files not stacking correctly in Jellyfin |
generate_move_plan | Generate rename/move plan for multi-version consolidation |
execute_move | Move or rename a file (Linux path → Windows UNC auto-convert). Use dry_run: true first |
refresh_library | Trigger a full Jellyfin library rescan |
analyze_tv_structure | Full structural audit of the TV library: duplicate series entries, release-pack folder names, episodes in per-episode subdirectories, wrong season numbers |
Setup
1. Install and build
npm install
npm run build
2. Configure environment
Copy .env.example to .env and fill in your values:
JELLYFIN_URL=http://your-jellyfin-server:8096
JELLYFIN_TOKEN=your_api_token
MOUNT_1_LINUX=/mnt/usb1
MOUNT_1_WINDOWS=\\your-nas\share
To find your API token: Jellyfin → Dashboard → API Keys.
3. Connect to VS Code Copilot
The .vscode/mcp.json file is already configured for this workspace.
Open VS Code, start a Copilot chat in Agent mode, and the jellyfin MCP server will be available.
Typical workflow
1. get_stats → overview of library health
2. find_missing_metadata → find files without TMDB/IMDB
3. analyze_duplicates sort_by=count → movies with the most duplicate versions
4. generate_move_plan tmdb_id=<id> → preview renames for one movie
5. execute_move dry_run=true → verify a single operation
6. execute_move dry_run=false → execute
7. refresh_library → Jellyfin picks up the changes
TV series audit
1. analyze_tv_structure → full structural report:
- duplicate series entries
- series folders with release-pack names
- episodes in per-episode subdirectories
- wrong season numbers (year/release parsed as season)
2. execute_move dry_run=true → verify a move before executing
3. execute_move dry_run=false → move the file/folder
4. refresh_library → Jellyfin picks up the changes
Path mapping
Jellyfin runs on Linux and reports paths like /mnt/usb1/Filmer/....
The server automatically converts these to Windows UNC paths for file operations
using the MOUNT_* environment variables. Add one pair per mount point:
MOUNT_1_LINUX=/mnt/usb1
MOUNT_1_WINDOWS=\\nas\share1
MOUNT_2_LINUX=/mnt/video
MOUNT_2_WINDOWS=\\nas\video
Project structure
src/
index.ts MCP server — tool definitions and handlers
jellyfin.ts Jellyfin REST API client
paths.ts Linux ↔ Windows UNC path conversion
quality.ts Video quality classification from filename
dist/ Compiled JavaScript
docs/
JELLYFIN-MEDIA-GUIDE.md Media organisation best practice guide
tv-serie-rapport.md TV series structural audit report
.vscode/
mcp.json VS Code Copilot MCP server configuration
.env.example Environment variable template
Documentation
See docs/JELLYFIN-MEDIA-GUIDE.md for the complete media organisation best practice guide, covering:
- Folder structure for movies, TV series, and anime
- Multi-version movies and CD-split naming
- NFO metadata files and artwork conventions
- Subtitle naming and external tracks
- Extras, trailers, and featurettes
- TV specials (Season 0) and anime naming
- Library scanning, performance, and plugin recommendations
Development
npm run dev # Run with tsx (no build step)
npm run build # Compile to dist/