Nicotine+ Soulseek MCP Server

Un servidor de Model Context Protocol (MCP) local y sin estado que se integra directamente con el motor de red Nicotine+ (Soulseek).

Permite a los asistentes de IA (como Claude Desktop, Antigravity u otros clientes MCP) buscar en la red peer-to-peer de Soulseek, evaluar calidad de audio / bitrates, seleccionar candidatos de descarga con la cola más corta y las velocidades más rápidas, descargar automáticamente listas de canciones completas y monitorizar el progreso de las transferencias.

Características

• Local y sin estado: Se ejecuta localmente a través de STDIO estándar usando el SDK oficial de MCP para Python.

• Detección automática de la configuración de escritorio de Nicotine+: Lee automáticamente tu configuración existente de escritorio de Nicotine+ (~/.config/nicotine/config o %APPDATA%/nicotine/config) y hereda tu cuenta de Soulseek y tus directorios de descarga sin necesidad de reentrarlos manualmente.

• Clasificación y puntuación inteligentes: Evalúa y clasifica los resultados de búsqueda según:

  • Calidad de audio (MP3 320 kbps, FLAC, V0, etc.)

  • Longitud de cola (priorizando usuarios con slots de subida libres / cola 0)

  • Velocidad de subida del usuario (en KB/s)

• Automatización masiva (auto_find_and_download): Pega una lista de canciones o álbumes en tu agente de IA; buscará, elegirá el archivo óptimo para cada uno y pondrá las descargas en cola automáticamente.

• Monitorización de transferencias en tiempo real (get_downloads_status): Permite seguir los porcentajes de progreso, la velocidad de descarga y posiciones en cola.

• Alta calidad de código: Construido con uv, anotaciones de tipos estrictas, esquemas Pydantic v2 y verificado con ruff y pytest.

Herramientas MCP disponibles

🚀 Configuración sin instalación de 1 minuto para agentes de IA

Puedes apuntar cualquier agente de IA (Claude Desktop, Antigravity, Cursor, Windsurf, Rhy, Roo Code, etc.) directamente a este repositorio de GitHub sin clonarlo ni gestionar entornos virtuales manualmente.

Recomendado: Zero-Install a través de uvx (macOS, Windows, Linux)

Añade esto a tu archivo de configuración de MCP (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "nicotine-plus": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ccombe/nicotine-plus-mcp@v0.2.0",
        "nicotine-mcp"
      ]
    }
  }
}

[!TIP]

• uvx descarga automáticamente, instala en una caché aislada y lanza el servidor bajo demanda.

• Puedes fijar una versión específica añadiendo @v0.2.0 (recomendado para estabilidad) o usar la rama master predeterminada si siempre quieres las últimas novedades.

💻 Instalación mediante clonado de Git local

Si prefieres clonar y ejecutar el servidor localmente:

git clone https://github.com/ccombe/nicotine-plus-mcp.git
cd nicotine-plus-mcp
uv run nicotine-mcp

Configuración local de MCP

macOS / Linux

{
  "mcpServers": {
    "nicotine-plus": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/nicotine-plus-mcp",
        "run",
        "nicotine-mcp"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "nicotine-plus": {
      "command": "uv.exe",
      "args": [
        "--directory",
        "C:\\path\\to\\nicotine-plus-mcp",
        "run",
        "nicotine-mcp"
      ]
    }
  }
}

[!NOTE] Detección automática multiplataforma:

• Linux: Usa automáticamente ~/.config/nicotine/config y $XDG_DATA_HOME/nicotine.

• macOS: Comprueba automáticamente ~/Library/Application Support/nicotine y ~/.config/nicotine.

• Windows: Usa automáticamente %APPDATA%\nicotine\config.

Si ya usas la aplicación de escritorio de Nicotine+ en tu máquina, no se requiere configuración ni credenciales. Si quieres especificar credenciales o rutas personalizadas, simplemente añade SOULSEEK_USERNAME, SOULSEEK_PASSWORD y SOULSEEK_DOWNLOAD_DIR al bloque env.

Ejemplo de uso con tu agente de IA

Puedes enviar peticiones como la siguiente:

"Por favor, busca y descarga las siguientes canciones en MP3 320 kbps, eligiendo a los usuarios con la velocidad más rápida y con espacio de subida libre:

1. Daft Punk - Around the World

2. Aphex Twin - Xtal

3. Boards of Canada - Dayvan Cowboy"

El agente ejecutará auto_find_and_download con la lista, y podrás ver el progreso en cualquier momento preguntando "¿Cómo van mis descargas?" (lo que llama a get_downloads_status).

Desarrollo, pruebas y verificación

Ejecuta de todas las suites de tests:

uv run pytest

Ejecuta el análisis de código (linter) y comprobador de formato (ruff):

uv run ruff check src/nicotine_mcp tests
uv run ruff format --check src/nicotine_mcp tests

Ejecuta la comprobación estricta de tipos con ty:

uv run ty check src/nicotine_mcp tests

Audita las dependencias en busca de vulnerabilidades de seguridad y verifica la integridad del lockfile:

uv run pip-audit
uv lock --check