Plex MCP Server

Servidor MCP de Plex

Este es un servidor MCP basado en Python que se integra con la API del Servidor de Medios de Plex para buscar películas y gestionar listas de reproducción. Utiliza la biblioteca PlexAPI para una interacción fluida con tu servidor Plex.

Capturas de pantalla

Aquí hay algunos ejemplos de cómo funciona el servidor MCP de Plex:

1. Buscar películas en la biblioteca de Plex por director

Busca películas en tu biblioteca de Plex especificando el nombre de un director. Por ejemplo, buscar "Alfred Hitchcock" devuelve una lista de sus películas en tu biblioteca.

---

2. Buscar películas faltantes para un director

Identifica películas de un director específico que faltan en tu biblioteca de Plex. Esto te ayuda a descubrir vacíos en tu colección.

---

3. Crear una lista de reproducción en tu biblioteca de Plex

Crea una nueva lista de reproducción en tu biblioteca de Plex utilizando las películas encontradas en una búsqueda. Esto te permite organizar tu biblioteca de manera eficiente.

Configuración

Requisitos previos

• Python 3.8 o superior
• uv gestor de paquetes
• Un Servidor de Medios de Plex con acceso a la API

Instalación

Instalación mediante Smithery

Para instalar la Integración del Servidor de Medios de Plex para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @djbriane/plex-mcp --client claude

Instalación manual

1. Clona este repositorio:

   git clone <repository-url>
   cd plex-mcp
   

2. Instala las dependencias con uv:

   uv venv
   source .venv/bin/activate
   uv sync
   

3. Configura las variables de entorno para tu servidor Plex:

   • PLEX_TOKEN: Tu token de autenticación de Plex
   • PLEX_SERVER_URL: La URL de tu servidor Plex (por ejemplo, http://192.168.1.100:32400)

Cómo encontrar tu token de Plex

Puedes encontrar tu token de Plex de esta manera:

• Inicia sesión en la aplicación web de Plex
• Abre las herramientas de desarrollador
• En la pestaña Consola, pega y ejecuta:

  window.localStorage.getItem('myPlexAccessToken')
  

Uso con Claude

Agrega la siguiente configuración a tu aplicación de Claude:

{
    "mcpServers": {
        "plex": {
            "command": "uv",
            "args": [
                "--directory",
                "FULL_PATH_TO_PROJECT",
                "run",
                "src/plex_mcp/plex_mcp.py"
            ],
            "env": {
                "PLEX_TOKEN": "YOUR_PLEX_TOKEN",
                "PLEX_SERVER_URL": "YOUR_PLEX_SERVER_URL"
            }
        }
    }
}

Comandos disponibles

El servidor MCP de Plex expone estos comandos:

Comando	Descripción	Referencia de OpenAPI
search_movies	Busca películas en tu biblioteca por varios filtros (por ejemplo, título, director, género) con soporte para un parámetro limit para controlar el número de resultados.	/library/sections/{sectionKey}/search
get_movie_details	Obtén información detallada sobre una película específica.	/library/metadata/{ratingKey}
get_movie_genres	Obtén los géneros de una película específica.	/library/sections/{sectionKey}/genre
list_playlists	Lista todas las listas de reproducción en tu servidor Plex.	/playlists
get_playlist_items	Obtén los elementos de una lista de reproducción específica.	/playlists/{playlistID}/items
create_playlist	Crea una nueva lista de reproducción con películas especificadas.	/playlists
delete_playlist	Elimina una lista de reproducción de tu servidor Plex.	/playlists/{playlistID}
add_to_playlist	Agrega una película a una lista de reproducción existente.	/playlists/{playlistID}/items
recent_movies	Obtén las películas agregadas recientemente de tu biblioteca.	/library/recentlyAdded

Ejecución de pruebas

Este proyecto incluye tanto pruebas unitarias como pruebas de integración. Usa las siguientes instrucciones para ejecutar cada tipo de prueba:

Pruebas unitarias

Las pruebas unitarias usan datos simulados para verificar la funcionalidad de cada módulo sin requerir un servidor Plex en vivo.

Para ejecutar todas las pruebas unitarias:

uv run pytest

Pruebas de integración

Las pruebas de integración se ejecutan contra un servidor Plex en vivo usando variables de entorno definidas en un archivo .env. Primero, crea un archivo .env en la raíz de tu proyecto con tu configuración de Plex:

PLEX_SERVER_URL=https://your-plex-server-url:32400
PLEX_TOKEN=yourPlexTokenHere

Las pruebas de integración están marcadas con el marcador de integración. Para ejecutar solo las pruebas de integración:

uv run pytest -m integration

Si estás experimentando problemas de conexión con tu servidor Plex, intenta ejecutar las pruebas de integración para ayudar a solucionar problemas.

Estilo de código y convenciones

• Estructura del módulo:
  Usa encabezados de sección claros para importaciones, configuración de registro, funciones de utilidad, definiciones de clases, ayudantes globales, métodos de herramientas y ejecución principal (protegida por if __name__ == "__main__":).

• Nomenclatura:
  Usa CamelCase para clases y lower_snake_case para funciones, variables y accesorios. En las pruebas, lista los accesorios integrados (por ejemplo, monkeypatch) antes que los personalizados.

• Documentación y comentarios:
  Incluye un docstring conciso para cada módulo, clase y función, con comentarios en línea para lógica compleja.

• Manejo de errores y registro:
  Usa el módulo logging de Python con mensajes de error consistentes (prefijo "ERROR:") y manejo explícito de excepciones.

• Patrones asíncronos:
  Define funciones vinculadas a E/S como async y usa asyncio.to_thread() para manejar operaciones de bloqueo.