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.
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: mcp-slskd
Archivo | Propósito |
| Servidor MCP de Node.js portátil. |
| Servidor MCP de PowerShell sin dependencias. |
| Scripts de Node.js y metadatos del paquete. |
| Utilidad experimental que evalúa búsquedas almacenadas. |
| Utilidad experimental para búsquedas limitadas y selección de FLAC. |
| Prototipo inicial de búsqueda masiva; usa ajustes conservadores. |
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.
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.
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.
Variable | Obligatoria | Valor por defecto | Descripción |
| Sí | — | Clave de API |
| No |
| URL base del servicio web/API de slskd. |
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.
Clona este repositorio y usa una ruta absoluta en tu configuración de MCP.
[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"][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.
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.142Ejecuta 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.
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.
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.
No se requieren paquetes Node de terceros.
npm run check
npm startEl 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.
401 UnauthorizedConfirma 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:5030Confirma 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 slskdLuego, desde Windows, verifica el endpoint reenviado:
Invoke-WebRequest http://localhost:5030 -UseBasicParsingSi 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.
message authentication code incorrectEsto 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 [::]:5030Algunos 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"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.
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.
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.
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.
List current and completed slskd downloads.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description conveys that this is a read-only enumeration and scopes it to 'current and completed' downloads, which covers the core behavior. However, with no annotations and no output schema, it does not disclose ordering, whether failed or queued items are excluded, or what fields the returned list contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to defining the tool's operation and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool, the description is mostly sufficient to invoke it correctly. The main gaps are the absence of an output schema and the lack of explicit detail about which download statuses are included, but the simplicity of the tool keeps these gaps minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the input schema is an empty object, so the schema already covers all invocation needs. The description correctly adds no parameter-specific detail, and the zero-parameter baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List') and a concrete resource ('current and completed slskd downloads'). It also distinguishes itself from sibling tools search_music and queue_download, which handle searching and enqueueing rather than enumerating existing downloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance about when to use this tool versus search_music or queue_download. No prerequisites, exclusion conditions, or alternative routing are mentioned; the appropriate use is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue one exact Soulseek result in slskd. Requires explicit confirmation that the user is authorized to download it.
| Name | Required | Description | Default |
|---|---|---|---|
| size | Yes | ||
| filename | Yes | ||
| username | Yes | ||
| rights_confirmed | Yes | True only after the user confirms they own or have permission to obtain this file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden, but it mostly restates the rights_confirmed parameter requirement already present in the schema. It does not disclose side effects, what happens after queuing, failure conditions, or output behavior, so it adds little beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler, making it easy to scan. It loses a point because part of the second clause duplicates the rights_confirmed parameter description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutating queue/download operation with no annotations, no output schema, and four required parameters, yet the description gives almost no operational context such as what happens after queuing or how to verify the exact result. An agent would need to infer too much to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The phrase 'one exact Soulseek result' hints that username, filename, and size form an exact identifier, but only 25% of parameters have schema descriptions and the tool description does not explain size units, filename expectations, or how these fields uniquely identify a result. It does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Queue'), a specific resource ('one exact Soulseek result'), and the system ('slskd'), so an agent immediately knows what the tool does. The action is clearly distinct from the sibling tools 'search_music' and 'list_downloads' without needing their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The wording implies this tool should be used when a specific Soulseek result has already been found and is ready to queue, but it never explicitly states when to use it versus the siblings or what conditions would make it inappropriate. The authorization requirement is a prerequisite, not guidance on choosing this tool among alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Soulseek through the user's local slskd instance. Use only for music the user is authorized to obtain.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| wait_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds useful context that the search hits an external P2P network via a local slskd instance and is restricted to authorized content. However, it does not disclose whether the search is blocking, what the results contain, or any rate/usage limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. The core action is front-loaded, and the authorization restriction earns its place as meaningful guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a network-search tool with no output schema and no annotations, this is under-specified. It omits parameter semantics, result-return behavior, and any connection to the sibling download/list workflow. The authorization note is helpful but does not make the definition complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. 'Search Soulseek' weakly implies what query means, but limit and especially wait_ms are entirely unexplained. An agent cannot confidently know how long to wait or how many results to expect from the description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Search' and a specific resource 'Soulseek through the user's local slskd instance,' and limits scope to music. This clearly distinguishes it from the sibling tools queue_download and list_downloads, which handle different stages of the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an authorization constraint ('Use only for music the user is authorized to obtain') but does not explicitly say when to prefer this over queue_download or list_downloads. The intended usage is only implied by the word 'Search' and the music scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0list_downloadsqueue_downloadsearch_musicScored across 3 tools
Each tool has a clear, non-overlapping purpose: searching, queueing a specific result, and listing downloads. An agent would not struggle to select the correct tool for a given step.
All tool names follow a consistent verb_noun pattern: search_music, queue_download, list_downloads. The naming is predictable and immediately conveys the action and target.
Three tools is a tight, well-scoped set for the core search-and-download workflow. Each tool earns its place without unnecessary bulk or overlap.
The surface covers the primary workflow of searching, queueing downloads, and checking progress. Missing management actions like canceling, pausing, or retrying downloads are minor gaps for the stated scope.
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
Agentic search over your Dewey document collections from any MCP-compatible client.
Search MCP servers, MCP clients and AI agents, and retrieve listing details. Free, read-only access.
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
