slskd MCP

Un servidor pequeño y con pocas dependencias del Model Context Protocol (MCP) para controlar una instancia existente de slskd.

Proporciona a un agente compatible con MCP tres herramientas:

• search_music — ejecuta una búsqueda en Soulseek y devuelve metadatos de pares/archivos.

• queue_download — pone en cola un resultado exacto tras una confirmación explícita de derechos.

• list_downloads — inspecciona las transferencias actuales y completadas.

Este proyecto no implementa el protocolo Soulseek. Se comunica con la API HTTP expuesta por tu propio servidor slskd.

[!IMPORTANT] Usa este software únicamente para obtener archivos que poseas, material de dominio público o con licencia libre, o archivos que tengas permiso de descargar. Eres responsable de cumplir la ley de derechos de autor y las normas que se apliquen en tu lugar de residencia.

Requisitos

• Una instancia de slskd en funcionamiento conectada a la red Soulseek.

• Una clave de API de slskd con el rol readwrite.

• Node.js 18 o superior, o PowerShell 7 o superior.

• Un cliente compatible con MCP como Codex.

Related MCP server: Soulseek MCP

Contenido del repositorio

Las utilidades por lotes son ejemplos operativos, no herramientas MCP genéricas. Revisa sus reglas de coincidencia, límites y estado local antes de usarlas con tu propia lista de pistas.

1. Configurar slskd

Añade una clave de API dedicada a slskd.yml. Las claves de API deben tener entre 16 y 255 caracteres.

web:
  port: 5030
  ip_address: "0.0.0.0"
  authentication:
    disabled: false
    username: "change-this-dashboard-username"
    password: "change-this-dashboard-password"
    api_keys:
      mcp:
        key: "replace-with-a-long-random-secret"
        role: readwrite
        cidr: "127.0.0.1/32,::1/128"

Genera un secreto de 32 bytes con PowerShell:

[Convert]::ToHexString(
  [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
)

Reinicia slskd después de cambiar su configuración.

Consideraciones sobre CIDR

El CIDR de solo bucle local anterior es adecuado cuando el servidor MCP se ejecuta en el mismo host que slskd o se conecta a través de un túnel SSH.

Con Docker, las solicitudes reenviadas desde el host pueden parecer originadas en la puerta de enlace del puente de Docker, como 172.17.0.1. Obtén la puerta de enlace real con:

docker inspect slskd --format '{{range .NetworkSettings.Networks}}{{.Gateway}}{{end}}'

Si es necesario, añade esa dirección exacta como entrada /32. Evita las claves de API sin restricciones, especialmente cuando slskd se expone a través de HTTP sin cifrar.

2. Configurar variables de entorno

PowerShell:

$env:SLSKD_URL = "http://localhost:5030"
$env:SLSKD_API_KEY = "your-api-key"

Shell POSIX:

export SLSKD_URL="http://localhost:5030"
export SLSKD_API_KEY="your-api-key"

No hagas commit de claves de API, contraseñas, archivos .env ni archivos de configuración de slskd con datos reales.

3. Configurar el cliente MCP

Clona este repositorio y usa una ruta absoluta en tu configuración de MCP.

Node.js

[mcp_servers.slskd]
command = "node"
args = ["/absolute/path/to/slskd-mcp/server.mjs"]
env_vars = ["SLSKD_URL", "SLSKD_API_KEY"]

Ejemplo en Windows:

[mcp_servers.slskd]
command = "node"
args = ["C:\\path\\to\\slskd-mcp\\server.mjs"]
env_vars = ["SLSKD_URL", "SLSKD_API_KEY"]

PowerShell 7

[mcp_servers.slskd]
command = "pwsh"
args = ["-NoProfile", "-File", "/absolute/path/to/slskd-mcp/server.ps1"]
env_vars = ["SLSKD_URL", "SLSKD_API_KEY"]

Reinicia el cliente MCP después de cambiar su configuración o las variables de entorno persistentes.

slskd remoto a través de SSH

Para una instancia de slskd en otra máquina, un túnel SSH mantiene la API fuera de internet pública:

ssh `
  -N `
  -o ServerAliveInterval=20 `
  -o ServerAliveCountMax=3 `
  -o TCPKeepAlive=yes `
  -o Compression=no `
  -o MACs=hmac-sha2-256-etm@openssh.com `
  -L 5030:127.0.0.1:5030 `
  root@208.68.38.142

Ejecuta esto en una ventana de PowerShell dedicada y mantenla abierta. Es normal que no haya salida tras el inicio de sesión: -N le indica a SSH que cree el túnel sin abrir un shell remoto. Configura SLSKD_URL=http://localhost:5030.

Si cambian la dirección del host o la cuenta SSH, sustituye root@208.68.38.142.

Uso

Indicaciones de ejemplo para el agente:

Search Soulseek for an authorized Creative Commons release by Artist Name.
Do not download anything yet.

Show the best unlocked FLAC matches with free upload slots and short queues.

I confirm I own this release. Queue the exact selected result.

La búsqueda y la descarga están separadas a propósito. queue_download requiere rights_confirmed: true.

Guía de búsqueda y carga

Las búsquedas de Soulseek son operaciones de red en vivo, no consultas de catálogo. Los resultados varían según la disponibilidad de los pares y pueden tardar varios segundos.

Para servidores pequeños, especialmente instancias con alrededor de 1 GB de memoria:

• Mantén bajas las búsquedas simultáneas.

• Procesa un lote por completo antes de comenzar otro.

• Comienza con lotes de 5–10 búsquedas.

• Evita imprimir colecciones completas de respuestas sin procesar a través del cliente MCP.

• Prefiere límites de resultados compactos y filtrado local exacto.

• Reutiliza las búsquedas completadas en lugar de repetirlas de inmediato.

Una búsqueda en verde/completada en el panel de slskd significa que la búsqueda terminó; no significa que se haya descargado un archivo.

Desarrollo

No se requieren paquetes Node de terceros.

npm run check
npm start

El servidor se comunica mediante JSON-RPC delimitado por saltos de línea en la entrada/salida estándar. Los registros de la aplicación y el texto de diagnóstico no deben escribirse en la salida estándar porque eso corrompería el transporte de MCP.

Solución de problemas

401 Unauthorized

• Confirma que SLSKD_API_KEY contiene la clave actual.

• Confirma que la clave tiene el rol readwrite.

• Verifica que su CIDR incluye la dirección que ve slskd, incluida la puerta de enlace del puente de Docker cuando corresponda.

• Reinicia el cliente MCP después de cambiar las variables de entorno persistentes.

Connection refused en localhost:5030

• Confirma que slskd se está ejecutando y escuchando en el puerto 5030.

• Si usas SSH, confirma que el proceso del túnel sigue en ejecución.

• Comprueba docker ps, docker logs slskd y ss -lntp | grep ':5030' en el servidor.

Primero comprueba slskd localmente en el VPS:

docker ps --filter name=slskd
curl -I --max-time 10 http://127.0.0.1:5030
docker logs --tail 30 slskd

Luego, desde Windows, verifica el endpoint reenviado:

Invoke-WebRequest http://localhost:5030 -UseBasicParsing

Si la comprobación en el VPS funciona pero la de Windows falla, detén el túnel antiguo con Ctrl+C en su ventana de PowerShell y vuelve a iniciarlo con el comando de la sección slskd remoto a través de SSH. No inicies nuevos lotes de búsqueda hasta que el túnel funcione y slskd informe de Connected, LoggedIn.

El túnel SSH informa de message authentication code incorrect

Esto significa que la conexión SSH se corrompió o se interrumpió; no es un error de autenticación de la API de slskd. Cierra la sesión SSH fallida y vuelve a conectarte. El comando de túnel anterior desactiva la compresión, selecciona un algoritmo moderno encrypt-then-MAC y activa los keepalives para detectar conexiones rotas con prontitud.

Si continúa:

• Revisa la consola del VPS para detectar presión de red, reinicios o errores del demonio SSH.

• Prueba la conexión desde una red diferente para descartar un middlebox defectuoso.

• Actualiza el cliente y el servidor OpenSSH.

• Ejecuta ssh -vvv root@208.68.38.142 para obtener salida de diagnóstico, teniendo cuidado de no compartir claves privadas, credenciales u otra salida sensible.

address already in use para [::]:5030

Algunos entornos Linux tratan un listener IPv6 como de doble pila, lo que provoca un conflicto con un listener IPv4. Configura solo una dirección:

web:
  port: 5030
  ip_address: "0.0.0.0"

Las descargas fallan mientras las búsquedas siguen apareciendo

Comprueba GET /api/v0/server o el panel de slskd. slskd debe informar de Connected, LoggedIn antes de poder resolver un par y poner en cola una descarga. Connected, LoggingIn no es suficiente.

slskd se desconecta repetidamente o agota el tiempo de espera

• Deja de enviar nuevas búsquedas.

• Permite que las búsquedas en cola se completen o cancélalas.

• Espera a que slskd se reconecte y alcance Connected, LoggedIn.

• Reanuda con un tamaño de lote más pequeño.

Notas de seguridad

• Trata la clave de API como una contraseña.

• Prefiere el acceso de bucle local más el túnel SSH para instancias remotas.

• No expongas públicamente el puerto 5030 sin HTTPS, autenticación, firewall y un CIDR cuidadosamente restringido.

• Usa una clave de API dedicada en lugar de reutilizar credenciales del panel o de Soulseek.

• Mantén las credenciales de Soulseek en slskd; este servidor MCP no las necesita.

Licencia

Este proyecto está dedicado al dominio público bajo CC0 1.0 Universal. Puedes copiarlo, modificarlo, distribuirlo y usarlo para cualquier propósito, incluido el comercial, sin pedir permiso.

CC0 se aplica únicamente al material propiedad de los contribuyentes de este proyecto. slskd, Soulseek y otro software o contenido de terceros conservan sus respectivas licencias y derechos.