Nicotine+ Soulseek MCP Server

Ein zustandsloser, rein lokaler Model Context Protocol (MCP)-Server, der direkt mit der Nicotine+- (Soulseek-) Netzwerk-Engine kommuniziert.

Er ermöglicht KI-Assistenten (wie Claude Desktop, Antigravity oder anderen MCP-Clients), das Soulseek-Peer-to-Peer-Netzwerk zu durchsuchen, Audioqualität/Bitraten zu bewerten, Download-Kandidaten mit der niedrigsten Warteschlange und den schnellsten Geschwindigkeiten auszuwählen, automatisch ganze Titellisten herunterzuladen und den Fortschritt der Übertragungen zu überwachen.

Funktionen

• Lokal & zustandslos: Läuft lokal über Standard-STDIO mit dem offiziellen Python-MCP-SDK.

• Erkennt die Desktop-Nicotine+-Konfiguration automatisch: Liest automatisch Ihre vorhandene Desktop-Nicotine+-Konfiguration (~/.config/nicotine/config oder %APPDATA%/nicotine/config) und übernimmt Ihr bestehendes Soulseek-Konto und Ihre Download-Verzeichnisse, ohne manuelle Eingabe.

• Intelligente Bewertung & Sortierung: Bewertet und sortiert Suchergebnisse basierend auf:

  • Audioqualität (320 kbps MP3, FLAC, V0 usw.)

  • Warteschlangenlänge (bevorzugt Peers mit freien Upload-Slots / 0 Warteschlange)

  • Upload-Geschwindigkeit des Peers (in KB/s)

• Bulk-Automatisierung (auto_find_and_download): Fügen Sie eine Liste von Songs oder Alben in Ihren KI-Agenten ein; er sucht, wählt für jeden die optimale Datei aus und stellt die Downloads automatisch in die Warteschlange.

• Echtzeit-Übertragungsüberwachung (get_downloads_status): Verfolgen Sie Fortschrittsprozente, Download-Geschwindigkeit und Warteschlangenpositionen.

• Hohe Codequalität: Erstellt mit uv, strengen Typannotationen, Pydantic-v2-Schemas und verifiziert mit ruff und pytest.

Verfügbare MCP-Tools

🚀 1-Minuten-Setup ohne Installation für KI-Agenten

Sie können jeden KI-Agenten (Claude Desktop, Antigravity, Cursor, Windsurf, Cline, Roo Code usw.) direkt auf dieses GitHub-Repository verweisen, ohne zu klonen oder virtuelle Umgebungen manuell zu verwalten.

Empfohlen: Zero-Install über uvx (macOS, Windows, Linux)

Fügen Sie dies zu Ihrer MCP-Einstellungsdatei hinzu (z. B. 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 lädt den Server automatisch herunter, installiert ihn in einem isolierten Cache und startet ihn bei Bedarf.

• Sie können eine bestimmte Release-Version durch Hinzufügen von @v0.2.0 festlegen (für Stabilität empfohlen) oder den Standard-master-Zweig verwenden, um immer die neuesten Updates zu erhalten.

💻 Lokales Git-Clone-Setup

Wenn Sie es vorziehen, den Server lokal zu klonen und auszuführen:

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

Lokale MCP-Konfiguration

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] Plattformübergreifende automatische Erkennung:

• Linux: Verwendet automatisch ~/.config/nicotine/config und $XDG_DATA_HOME/nicotine.

• macOS: Prüft automatisch ~/Library/Application Support/nicotine und ~/.config/nicotine.

• Windows: Verwendet automatisch %APPDATA%\nicotine\config.

Wenn Sie die Nicotine+-Desktop-App bereits auf Ihrem Rechner verwenden, sind keine Einrichtung oder Anmeldedaten erforderlich. Wenn Sie benutzerdefinierte Anmeldedaten oder Pfade angeben möchten, fügen Sie einfach SOULSEEK_USERNAME, SOULSEEK_PASSWORD und SOULSEEK_DOWNLOAD_DIR zum env-Block hinzu.

Beispielverwendung mit Ihrem KI-Agenten

Sie können Aufforderungen wie diese einfügen:

"Bitte suchen und laden Sie die folgenden Titel als 320-kbps-MP3 herunter, wählen Sie die schnellsten Peers mit freien Upload-Slots:

1. Daft Punk - Around the World

2. Aphex Twin - Xtal

3. Boards of Canada - Dayvan Cowboy"

Der Agent führt auto_find_and_download mit der Liste aus, und Sie können den Fortschritt jederzeit überprüfen, indem Sie fragen: "Wie laufen meine Downloads?" (was get_downloads_status aufruft).

Entwicklung, Tests & Verifizierung

Führen Sie alle Test-Suiten aus:

uv run pytest

Führen Sie den Code-Linter & Formatprüfer (ruff) aus:

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

Führen Sie die strenge Typprüfung mit ty aus:

uv run ty check src/nicotine_mcp tests

Prüfen Sie Abhängigkeiten auf Sicherheitslücken & Lockfile-Integrität:

uv run pip-audit
uv lock --check