Servidor Plex MCP

Este es un servidor MCP basado en Python que se integra con la API de Plex Media Server para buscar películas y administrar listas de reproducción. Utiliza la biblioteca PlexAPI para una interacción fluida con su servidor Plex.

Capturas de pantalla

A continuación se muestran algunos ejemplos de cómo funciona el servidor Plex MCP:

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

Busca películas en tu biblioteca de Plex especificando el nombre del director. Por ejemplo, si buscas "Alfred Hitchcock", obtendrás una lista de sus películas en tu biblioteca.

2. Encuentra películas que faltan para un director

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

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

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

Configuración

Prerrequisitos

Python 3.8 o superior
administrador de paquetes uv
Un servidor multimedia Plex con acceso API

Instalación

Instalación mediante herrería

Para instalar Plex Media Server Integration para Claude Desktop automáticamente a través de Smithery :

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

Instalación manual

Clonar este repositorio:
git clone <repository-url> cd plex-mcp
Instalar dependencias con uv :
uv venv source .venv/bin/activate uv sync
Configure las variables de entorno para su servidor Plex:
- PLEX_TOKEN : Su token de autenticación de Plex
- PLEX_SERVER_URL : la URL de su servidor Plex (por ejemplo, http://192.168.1.100:32400 )

Cómo encontrar tu token Plex

Puedes encontrar tu token Plex de esta manera:

Iniciar sesión en la aplicación web de Plex
Herramientas abiertas para desarrolladores
En la pestaña Consola, pegue y ejecute:
window.localStorage.getItem('myPlexAccessToken')

Uso con Claude

Añade la siguiente configuración a tu aplicación 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 Plex MCP expone estos comandos:

Dominio	Descripción	Referencia de OpenAPI
`search_movies`	Busque películas en su biblioteca mediante varios filtros (por ejemplo, título, director, género) con soporte para un parámetro `limit` para controlar la cantidad de resultados.	`/library/sections/{sectionKey}/search`
`get_movie_details`	Obtenga información detallada sobre una película específica.	`/library/metadata/{ratingKey}`
`get_movie_genres`	Obtenga los géneros de una película específica.	`/library/sections/{sectionKey}/genre`
`list_playlists`	Enumere todas las listas de reproducción en su servidor Plex.	`/playlists`
`get_playlist_items`	Obtenga 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 específicas.	`/playlists`
`delete_playlist`	Eliminar una lista de reproducción de su servidor Plex.	`/playlists/{playlistID}`
`add_to_playlist`	Agregar una película a una lista de reproducción existente.	`/playlists/{playlistID}/items`
`recent_movies`	Obtén películas agregadas recientemente a tu biblioteca.	`/library/recentlyAdded`

Ejecución de pruebas

Este proyecto incluye pruebas unitarias y de integración. Utilice las siguientes instrucciones para ejecutar cada tipo de prueba:

Pruebas unitarias

Las pruebas unitarias utilizan datos ficticios para verificar la funcionalidad de cada módulo sin necesidad de 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 en un servidor Plex activo utilizando variables de entorno definidas en un archivo .env. Primero, cree un archivo .env en la raíz del proyecto con su configuración de Plex:

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

Las pruebas de integración se marcan con el marcador de integración. Para ejecutar solo las pruebas de integración:

uv run pytest -m integration

Si tiene problemas de conexión con su servidor Plex, intente ejecutar las pruebas de integración para ayudar a solucionar el problema.

Estilo y convenciones del código

Estructura del módulo:
Utilice encabezados de sección claros para importaciones, configuración de registro, funciones de utilidad, definiciones de clase, ayudantes globales, métodos de herramientas y ejecución principal (protegidos por if __name__ == "__main__": ).
Nombre:
Use CamelCase para las clases y lower_snake_case para funciones, variables y accesorios. En las pruebas, enumere los accesorios integrados (p. ej., monkeypatch ) antes que los personalizados.
Documentación y comentarios:
Incluya una cadena de documentación concisa para cada módulo, clase y función, con comentarios en línea para una lógica compleja.
Manejo y registro de errores:
Utilice el módulo logging de Python con mensajes de error consistentes (prefijo “ERROR:”) y manejo explícito de excepciones.
Patrones asincrónicos:
Defina funciones limitadas de E/S como asíncronas y utilice asyncio.to_thread() para manejar operaciones de bloqueo.

Plex MCP Server

Integrations