convez.ai
MCP ServerAutomaçãoIntermediário
FrankBurmo

Jellyfin MCP

FrankBurmo/jellyfin-mcp

Gerencie sua biblioteca Jellyfin conversando com Copilot

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 dias
Versão
—
Issues abertas
0
Contribuidores
5

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

ToolDescription
get_statsQuick health overview: total counts, missing metadata, duplicate groups
find_missing_metadataFind movies/series missing TMDB and/or IMDB identifiers
analyze_duplicatesGroup by TMDB ID, classify quality per version (2160p/1080p/SD, Bluray/WEB/DVD)
find_cd_splitsFind CD-split files not stacking correctly in Jellyfin
generate_move_planGenerate rename/move plan for multi-version consolidation
execute_moveMove or rename a file (Linux path → Windows UNC auto-convert). Use dry_run: true first
refresh_libraryTrigger a full Jellyfin library rescan
analyze_tv_structureFull 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/
Ver o original no GitHub

Bom para

Relacionados