Servidor MCP de Plex

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona 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?"

• "Busca películas de acción en mi biblioteca"

• "¿Qué hay en mi lista de continuar viendo?"

• "Añade 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"

Related MCP server: YARR Media Stack MCP Server

Características

45 herramientas listas para usar (54 con operaciones de escritura habilitadas):

• Gestión de la biblioteca de Plex — Explora bibliotecas, busca contenido multimedia, obtén metadatos detallados, lista listas de reproducción y listas de seguimiento.

• Análisis al estilo Tautulli — Estadísticas de visualización, actividad del usuario, 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, añade series/películas, visualiza colas, activa descargas.

• Sincronización con Trakt.tv — Autenticación OAuth, sincronización del historial de visualización, estadísticas mejoradas, scrobbling. Cuando se configura, los datos de Trakt enriquecen las recomendaciones al capturar películas vistas fuera de Plex.

• Operaciones de escritura (opcional) — Crea/edita listas de reproducción, actualiza metadatos, gestiona la lista de seguimiento.

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 configurarlo todo desde el principio.

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 instálalo directamente desde npm:

npx plex-mcp-server

Configuración

1. Obtén tu token de Plex (consulta las instrucciones a continuación)

2. Configura tu cliente MCP (ej. 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 explicando cómo configurarlos, en lugar de bloquear el servidor.

Las claves API de Sonarr/Radarr se pueden encontrar en Settings > General > API Key en la interfaz web de cada aplicación.

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

En la versión v1.0.x había tres binarios de servidor separados (build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js). En la versión v1.1.0+ estos son reemplazados 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 preguntarle 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:

1. Configura las credenciales de Trakt (ver arriba)

2. Pregunta: "Autentícate con Trakt" — sigue el flujo OAuth

3. Pregunta: "Haz una prueba de sincronización de mi historial de Plex a Trakt" — previsualiza lo que se sincronizaría

4. Pregunta: "Sincroniza mi historial de visualización de Plex con Trakt" — ejecuta la sincronización real

Buscar y añadir nuevo contenido:

1. Pregunta: "Busca en Sonarr The Beverly Hillbillies" — encuentra el ID de TVDB

2. Pregunta: "Añade The Beverly Hillbillies a Sonarr" — detecta automáticamente los perfiles de calidad y las carpetas raíz

3. Pregunta: "¿Qué hay en mi cola de descargas de Sonarr?" — monitorea el progreso

Obtener recomendaciones personalizadas:

1. Pregunta: "Recomiéndame algunas películas de mi biblioteca"

2. El motor analiza tu historial de visualización: géneros, directores, actores, calificaciones

3. Puntúa cada película no vista y devuelve las mejores coincidencias con razones

4. Para servidores multiusuario, especifica el usuario: "Recomienda películas para Titus"

5. Si Trakt está configurado, también utiliza automáticamente tu historial de Trakt, capturando películas que viste fuera de Plex (otras plataformas, antes de que se configurara el seguimiento)

Análisis de visualización multiplataforma:

1. Pregunta: "Muéstrame mis estadísticas de visualización de Plex de los últimos 30 días"

2. Pregunta: "¿Cuáles son mis estadísticas de Trakt?" — mira las estadísticas de por vida (películas vistas, horas, hitos)

3. Pregunta: "¿Cuáles son mis películas más populares este mes?"

Funciones disponibles

Herramientas de Plex (19 herramientas)

Operaciones de escritura (9 herramientas, opcional)

Establece PLEX_ENABLE_MUTATIVE_OPS=true para habilitar estas herramientas. Permiten que tu asistente de IA realice cambios en tu servidor Plex. Úsalas con precaución; aunque probamos estas herramientas, no hay garantías. Revisa los cambios que propone tu asistente antes de confirmar.

Herramientas de Sonarr (8 herramientas)

Herramientas de Radarr (8 herramientas)

Herramientas entre servicios (1 herramienta)

Herramientas de Trakt (9 herramientas)

Obtener tu token de Plex

1. Abre la aplicación web de Plex en tu navegador

2. Navega a Configuración > Cuenta > Privacidad

3. Haz clic en "Mostrar avanzado" en la parte inferior

4. Copia tu token de Plex

Método alternativo:

• Visita: http://TU_IP_PLEX:32400/web/index.html#!/settings/account

• Busca el campo "Plex Token"

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

Construcción desde el código fuente

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

Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar una solicitud de extracción (Pull Request). Para cambios importantes, abre primero un issue para discutir lo que te gustaría cambiar.

Directrices de desarrollo

1. Haz un fork del repositorio

2. Crea una rama de características (git checkout -b feature/amazing-feature)

3. Confirma tus cambios (git commit -m 'Add amazing feature')

4. Empuja a la rama (git push origin feature/amazing-feature)

5. Abre una solicitud de extracción

Solución de problemas

Problemas comunes

Conexión rechazada:

• Verifica que tu servidor Plex esté ejecutándose

• Comprueba la PLEX_URL en la configuración de tu entorno

• Asegúrate de que el puerto (generalmente 32400) sea correcto

Errores de autenticación:

• Verifica que tu token de Plex sea correcto

• Comprueba los permisos del token en la configuración de Plex

• Asegúrate de que el token no haya caducado

Respuestas vacías:

• Algunas funciones requieren Plex Pass

• Comprueba si tus bibliotecas son accesibles

• Verifica que el contenido multimedia haya sido escaneado y esté disponible

Problemas de conexión con Sonarr/Radarr:

• Verifica que Sonarr/Radarr se esté ejecutando y sea accesible desde el host del servidor MCP

• Comprueba que la clave API sea correcta (Settings > General > API Key)

• Sonarr usa la API v3 en /api/v3/: asegúrate de que tu URL no incluya una ruta final

• Para bibliotecas grandes de Radarr (más de 20k películas), la llamada inicial radarr_get_movies puede tardar hasta 30 segundos

Problemas de autenticación de Trakt:

• Asegúrate de que TRAKT_CLIENT_ID y TRAKT_CLIENT_SECRET estén configurados

• Usa la herramienta trakt_authenticate para iniciar