Plex

Proporciona a los asistentes de IA acceso completo a un Plex Media Server.

Documentación

Servidor MCP de Plex

Un servidor Model Context Protocol (MCP) que brinda a los asistentes de IA acceso integral a tu Plex Media Server, Sonarr, Radarr y Trakt.tv, todo desde un único servidor unificado.

¿Qué es esto?

Este servidor MCP transforma tu Plex Media Server en una base de datos consultable por IA. Haz preguntas a tu asistente de IA como:

"¿Qué películas he visto recientemente?"
"Muéstrame mis estadísticas de visualización del último mes"
"¿Cuál es el contenido más popular en mi servidor?"
"Encuentra películas de acción en mi biblioteca"
"¿Qué hay en mi lista de continuar viendo?"
"Agrega esa nueva serie a Sonarr"
"¿Qué hay en mi cola de descargas?"
"Sincroniza mi historial de visualización con Trakt"
"Recomiéndame algunas películas que no haya visto"

Características

46 herramientas listas para usar (58 con operaciones de escritura habilitadas):

Gestión de biblioteca de Plex — Explora bibliotecas, busca medios, obtén metadatos detallados, lista listas de reproducción y lista de seguimiento
Analíticas estilo Tautulli — Estadísticas de visualización, actividad de usuarios, contenido popular, historial de visualización
Recomendaciones personalizadas — Sugerencias de películas impulsadas por IA basadas en tu historial de visualización, géneros, directores y actores. Admite perfiles por usuario para servidores Plex multiusuario.
Integración con Sonarr/Radarr — Explora, busca, agrega series/películas, consulta colas, activa descargas
Sincronización con Trakt.tv — Autenticación OAuth, sincronización de historial de visualización, estadísticas mejoradas, scrobbling. Cuando está configurado, los datos de Trakt enriquecen las recomendaciones al detectar películas vistas fuera de Plex.
Operaciones de escritura (opt-in) — Crea/edita listas de reproducción, actualiza metadatos, gestiona la lista de seguimiento, califica medios y marca medios como vistos o no vistos

Un servidor, todas las herramientas. Las credenciales de Trakt y Sonarr/Radarr son opcionales: las herramientas que las necesitan devuelven un mensaje de configuración útil si falta la clave. No necesitas configurar todo de antemano.

Inicio rápido

Requisitos previos

Node.js 20+
Plex Media Server (cualquier versión reciente)
Token de Plex (Cómo obtener tu token)
Cliente compatible con MCP (Claude Desktop, etc.)

Instalación

# Clone the repository
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

O instala directamente desde npm:

npx plex-mcp-server

Configuración

Obtén tu token de Plex (consulta las instrucciones a continuación)
Configura tu cliente MCP (por ejemplo, Claude Desktop):

{
  "mcpServers": {
    "plex": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/plex-mcp-server.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",

        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "optional_sonarr_api_key",

        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "optional_radarr_api_key",

        "TRAKT_CLIENT_ID": "optional_trakt_client_id",
        "TRAKT_CLIENT_SECRET": "optional_trakt_client_secret"
      }
    }
  }
}

Solo se requiere PLEX_TOKEN. Todas las demás credenciales son opcionales: las herramientas para servicios no configurados devuelven un mensaje de error claro que explica cómo configurarlos, en lugar de bloquear el servidor.

Claves API de Sonarr/Radarr se pueden encontrar en Configuración > General > Clave API en la interfaz web de cada aplicación.

Configuración de Trakt.tv requiere una aplicación OAuth de Trakt. Crea una con la URI de redirección urn:ietf:wg:oauth:2.0:oob, luego agrega el ID de cliente y el secreto a tu configuración. Una vez que el servidor esté en ejecución, pide a tu asistente de IA que "autentique con Trakt": te guiará a través del flujo OAuth. Consulta la guía de configuración de Trakt para obtener instrucciones detalladas.

Respuestas compactas (opcional)

Las herramientas responden con JSON de forma predeterminada. Configurar PLEX_OUTPUT_FORMAT=toon las cambia a TOON, que escribe una matriz de registros una vez como encabezado y luego como filas en lugar de repetir cada nombre de campo en cada registro:

results[3]{ratingKey,title,year}:
  1001,Arrival,2016
  1002,Sicario,2015
  1003,Dune,2021

Eso son los mismos datos que tu asistente habría recibido, en menos tokens: aproximadamente un tercio menos en una variedad de respuestas de herramientas, y entre un 40 y un 60 % menos en las de tipo lista como search_media, get_library_items y radarr_get_movies. El ahorro solo vale la pena en listas largas, por lo que cada respuesta se emite en TOON solo cuando TOON es realmente más corto, y como JSON en caso contrario; habilitar esto no puede hacer que una respuesta sea más grande de lo que es hoy.

"env": {
  "PLEX_TOKEN": "your_plex_token_here",
  "PLEX_OUTPUT_FORMAT": "toon"
}

Deja la variable sin configurar (el valor predeterminado) y las respuestas serán, byte por byte, el JSON que siempre han sido.

¿Migrando desde v1.0.x?

En v1.0.x había tres binarios de servidor separados (build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js). En v1.1.0+ estos se reemplazan por un único binario unificado: build/plex-mcp-server.js.

Los binarios antiguos siguen funcionando pero emiten una advertencia de obsolescencia. Actualiza tu configuración de MCP para apuntar a build/plex-mcp-server.js y elimina cualquier entrada de servidor duplicada.

Consulta la guía de migración para obtener todos los detalles.

Uso

Una vez configurado, puedes preguntar a tu asistente de IA:

"What movies did I watch last week?"
"Show me my most popular TV shows this month"
"Give me viewing statistics for the past 30 days"
"Search for Night of the Living Dead in my library"
"What's on my continue watching list?"
"List all my Plex libraries"
"Add that new show to Sonarr"
"What's in my Radarr download queue?"
"Sync my Plex history to Trakt"

Flujos de trabajo recomendados

Sincronizar el historial de visualización de Plex con Trakt:

Configura las credenciales de Trakt (consulta arriba)
Pregunta: "Autentícate con Trakt" — sigue el flujo OAuth
Pregunta: "Haz una sincronización de prueba de mi historial de Plex a Trakt" — previsualiza lo que se sincronizaría
Pregunta: "Sincroniza mi historial de visualización de Plex con Trakt" — ejecuta la sincronización real

Encontrar y agregar contenido nuevo:

Pregunta: "Busca en Sonarr The Beverly Hillbillies" — encuentra el ID de TVDB
Pregunta: "Agrega The Beverly Hillbillies a Sonarr" — detecta automáticamente los perfiles de calidad y las carpetas raíz
Pregunta: "¿Qué hay en mi cola de descargas de Sonarr?" — supervisa el progreso

Obtener recomendaciones personalizadas:

Pregunta: "Recomiéndame algunas películas de mi biblioteca"
El motor analiza tu historial de visualización: géneros, directores, actores, calificaciones
Puntúa cada película no vista y devuelve las mejores coincidencias con razones
Para servidores multiusuario, especifica el usuario: "Recomienda películas para Titus"
Si Trakt está configurado, también usa automáticamente tu historial de Trakt, detectando películas que viste fuera de Plex (otras plataformas, antes de que se configurara el seguimiento)

Analíticas de visualización multiplataforma:

Pregunta: "Muéstrame mis estadísticas de visualización de Plex de los últimos 30 días"
Pregunta: "¿Cuáles son mis estadísticas de Trakt?" — consulta estadísticas de por vida (películas vistas, horas, hitos)
Pregunta: "¿Cuáles son mis películas más populares este mes?"

Funciones disponibles

46 herramientas listas para usar (58 con operaciones de escritura habilitadas).

Herramientas de Plex (20 herramientas)

Función	Descripción
`get_libraries`	Lista todas las bibliotecas de Plex
`get_library_items`	Lista elementos en una biblioteca con paginación
`export_library`	Exporta una biblioteca completa a JSON (bajo `./exports`)
`search_media`	Busca medios globalmente o dentro de una biblioteca
`get_recently_added`	Contenido agregado recientemente
`get_on_deck`	Lista de continuar viendo
`get_media_details`	Información detallada de medios
`get_editable_fields`	Muestra campos editables y etiquetas disponibles para un elemento
`get_playlists`	Lista todas las listas de reproducción de Plex
`get_playlist_items`	Lista elementos en una lista de reproducción
`get_watchlist`	Obtiene la lista de seguimiento de la cuenta actual desde Plex Discover
`get_recently_watched`	Contenido visto recientemente
`get_watch_history`	Sesiones de visualización detalladas
`get_fully_watched`	Películas/programas completamente vistos
`get_watch_stats`	Estadísticas de visualización integrales
`get_user_stats`	Estadísticas de actividad de usuarios
`get_library_stats`	Métricas de uso de la biblioteca
`get_popular_content`	Análisis de contenido más popular
`get_recommendations`	Recomendaciones personalizadas de películas basadas en tu historial de visualización
`get_active_sessions`	Transmisiones de Plex actualmente activas: quién está viendo qué, estado del reproductor, transcodificación

Operaciones de escritura (12 herramientas, opt-in)

Configura PLEX_ENABLE_MUTATIVE_OPS=true para habilitar estas herramientas. Permiten que tu asistente de IA realice cambios en tu servidor Plex. Úsalas con cuidado: aunque probamos estas herramientas, no hay garantías. Revisa los cambios que proponga tu asistente antes de confirmarlos.

Función	Descripción
`update_metadata`	Actualiza campos de metadatos y etiquetas editables para un elemento de medios
`update_metadata_from_json`	Aplica un payload JSON de metadatos usando mapeo de campos de mejor esfuerzo
`create_playlist`	Crea una nueva lista de reproducción inteligente o estática
`add_to_playlist`	Agrega un elemento de medios a una lista de reproducción
`remove_from_playlist`	Elimina un elemento de una lista de reproducción
`clear_playlist`	Previsualiza y opcionalmente vacía todos los elementos de una lista de reproducción (`confirm=true`)
`delete_playlist`	Elimina una lista de reproducción sin eliminar los medios subyacentes
`add_to_watchlist`	Agrega una película o programa local coincidente a la lista de seguimiento de la cuenta
`remove_from_watchlist`	Elimina un elemento de la lista de seguimiento de la cuenta por su GUID global de Plex o clave de calificación local
`rate_media`	Establece la calificación del usuario para un elemento de medios de 0 a 10
`mark_watched`	Marca un elemento de medios como visto
`mark_unwatched`	Marca un elemento de medios como no visto

Herramientas de Sonarr (8 herramientas)

Función	Descripción
`sonarr_get_series`	Lista series con filtro de título opcional
`sonarr_search`	Busca en TheTVDB nuevas series
`sonarr_add_series`	Agrega series por ID de TVDB
`sonarr_get_missing`	Episodios faltantes/deseados
`sonarr_get_queue`	Cola de descargas
`sonarr_get_calendar`	Próximos episodios
`sonarr_get_profiles`	Perfiles de calidad y carpetas raíz
`sonarr_trigger_search`	Activa la búsqueda de episodios faltantes

Herramientas de Radarr (8 herramientas)

Función	Descripción
`radarr_get_movies`	Lista películas con filtro de título opcional
`radarr_search`	Busca en TMDB nuevas películas
`radarr_add_movie`	Agrega películas por ID de TMDB
`radarr_get_missing`	Películas faltantes/deseadas
`radarr_get_queue`	Cola de descargas
`radarr_get_calendar`	Próximas películas
`radarr_get_profiles`	Perfiles de calidad y carpetas raíz
`radarr_trigger_search`	Activa la búsqueda de películas faltantes

Herramientas entre servicios (1 herramienta)

Función	Descripción
`arr_get_status`	Verifica el estado de conexión de Sonarr/Radarr

Herramientas de Trakt (9 herramientas)

Función	Descripción
`trakt_authenticate`	Inicia el flujo OAuth de Trakt.tv
`trakt_complete_auth`	Completa la autenticación
`trakt_get_auth_status`	Verifica el estado de autenticación
`trakt_sync_to_trakt`	Sincroniza el historial de Plex con Trakt
`trakt_sync_from_trakt`	Obtiene datos de Trakt para comparación
`trakt_get_user_stats`	Estadísticas mejoradas de Trakt
`trakt_search`	Busca en la base de datos de Trakt
`trakt_start_scrobbling`	Scrobbling en tiempo real
`trakt_get_sync_status`	Verifica el estado de la operación de sincronización

Cómo obtener tu token de Plex

Abre la aplicación web de Plex en tu navegador
Navega a Configuración > Cuenta > Privacidad
Haz clic en "Mostrar avanzado" en la parte inferior
Copia tu token de Plex

Método alternativo:

Visita: http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account
Busca el campo "Token de Plex"

Estructura del proyecto

plex-mcp-server/
├── src/
│   ├── plex-mcp-server.ts    # Unified server entry point (44+ tools)
│   ├── index.ts               # Deprecated shim → plex-mcp-server
│   ├── plex-arr-server.ts     # Deprecated shim → plex-mcp-server
│   ├── plex-trakt-server.ts   # Deprecated shim → plex-mcp-server
│   ├── plex/                  # Shared Plex module
│   │   ├── client.ts          #   Plex API client
│   │   ├── tools.ts           #   Plex tool implementations
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── arr/                   # Sonarr/Radarr module
│   │   ├── client.ts          #   Base ArrClient + Sonarr/Radarr subclasses
│   │   ├── mcp-functions.ts   #   Tool implementations (17 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── trakt/                 # Trakt.tv module
│   │   ├── client.ts          #   Trakt API client + OAuth
│   │   ├── sync.ts            #   Plex-to-Trakt sync engine
│   │   ├── mapper.ts          #   Plex-to-Trakt data mapping
│   │   ├── mcp-functions.ts   #   Tool implementations (9 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   └── tool-schemas.ts    #   MCP tool schema definitions
│   ├── shared/                # Shared utilities
│   │   └── utils.ts           #   truncate, sleep, chunkArray
│   └── __tests__/             # Test suite (94 tests)
├── build/                     # Compiled JavaScript output
├── docs/                      # Documentation
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example               # Environment variables template
└── README.md

Desarrollo

Scripts

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch

Compilar desde el código fuente

git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install
npm run dev

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una solicitud de extracción (Pull Request). Para cambios importantes, abre primero un issue para discutir lo que te gustaría cambiar.

Los contribuyentes fusionados reciben crédito en CONTRIBUTORS.md. Usa Conventional Commits: las versiones y el registro de cambios se generan a partir de ellos; consulta docs/RELEASING.md.

Pautas de desarrollo

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Confirma tus cambios (git commit -m 'Add amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre una solicitud de extracción

Solución de problemas

Problemas comunes

Conexión rechazada:

Verifica que tu servidor Plex esté en ejecución
Revisa el PLEX_URL en tu configuración de entorno
Asegúrate de que el puerto (generalmente 32400) sea correcto Host inalcanzable (EHOSTUNREACH / errores de conexión) en macOS:
En macOS Sequoia, Sonoma o versiones posteriores, las conexiones a direcciones IP locales (como 10.0.0.10 o 192.168.1.50) pueden estar bloqueadas por la configuración de Privacidad de red local.
Solución 1: Intente conectarse usando el nombre de host local (por ejemplo, plex.local o el nombre de su servidor Plex) en lugar de la dirección IP directa. Alternativamente, use un dominio *.plex.direct de Plex.
Solución 2: Vaya a Configuración del sistema -> Privacidad y seguridad -> Red local en su Mac y asegúrese de que el cliente MCP (por ejemplo, Claude Desktop, Terminal o VS Code) esté habilitado y tenga permiso para acceder a la red local.

Errores de autenticación:

Verifique que su token de Plex sea correcto
Compruebe los permisos del token en la configuración de Plex
Asegúrese de que el token no haya caducado

Respuestas vacías:

Algunas funciones requieren Plex Pass
Compruebe si sus bibliotecas son accesibles
Verifique que los medios hayan sido escaneados y estén disponibles

Problemas de conexión con Sonarr/Radarr:

Verifique que Sonarr/Radarr esté ejecutándose y sea accesible desde el host del servidor MCP
Compruebe que la clave API sea correcta (Configuración > General > Clave API)
Sonarr usa API v3 en /api/v3/ — asegúrese de que su URL no incluya una ruta final
Para bibliotecas grandes de Radarr (más de 20,000 películas), la llamada inicial a radarr_get_movies puede tardar hasta 30 segundos

Problemas de autenticación con Trakt:

Asegúrese de que TRAKT_CLIENT_ID y TRAKT_CLIENT_SECRET estén configurados
Use la herramienta trakt_authenticate para iniciar el flujo OAuth
Complete la autenticación con trakt_complete_auth usando el código de Trakt

Problemas con el cliente MCP:

Asegúrese de que la ruta esté configurada en build/plex-mcp-server.js (el servidor unificado)
Compruebe que Node.js esté en el PATH de su sistema
Verifique que las variables de entorno estén configuradas en la configuración del cliente

Obtener Ayuda

Abrir un problema
Consulte las discusiones existentes
Revise la documentación de MCP

Requisitos

Node.js 20.0.0 o superior
Plex Media Server (cualquier versión reciente)
Acceso de red entre el servidor MCP y el servidor Plex
Token de Plex válido con los permisos adecuados

Notas de Seguridad

Mantenga su token de Plex seguro — nunca lo envíe al control de versiones
Use variables de entorno para la configuración sensible
Ejecute en redes confiables — el servidor se comunica directamente con Plex
Rotación regular de tokens — considere actualizar los tokens periódicamente
Las operaciones de escritura están deshabilitadas por defecto — actívelas solo si confía en el criterio de su asistente de IA

Licencia

Este proyecto está licenciado bajo la Licencia MIT — consulte el archivo LICENCIA para más detalles.

Agradecimientos

Todos los que han contribuido con código — este proyecto no es un esfuerzo individual
Anthropic por el Protocolo de Contexto de Modelo
Plex por el increíble servidor multimedia
Tautulli por la inspiración analítica
La comunidad de código abierto por varias bibliotecas y herramientas

Proyectos Relacionados

Protocolo de Contexto de Modelo - El estándar que implementa este servidor
Claude Desktop - Cliente MCP popular
Tautulli - Monitoreo y análisis de Plex
PlexAPI - Biblioteca API de Plex para Python

Hecho con amor para la comunidad de Plex y IA