Сервер Nicotine+ Soulseek MCP

Stateless-сервер Model Context Protocol (MCP), работающий только локально и взаимодействующий напрямую с сетевым движком Nicotine+ (Soulseek).

Он позволяет ИИ-ассистентам (таким как Claude Desktop, Antigravity или другим MCP-клиентам) искать в пиринговой сети Soulseek, оценивать качество аудио/битрейт, выбирать кандидатов для загрузки с наименьшей очередью и самой быстрой скоростью, автоматически загружать массовые списки треков и отслеживать ход передачи.

Возможности

• Локальный и Stateless: работает локально через стандартный STDIO с использованием официального Python MCP SDK.

• Автоопределение конфигурации десктопного Nicotine+: автоматически считывает вашу существующую конфигурацию десктопного Nicotine+ (~/.config/nicotine/config или %APPDATA%/nicotine/config), наследуя вашу существующую учётную запись Soulseek и каталоги загрузки без ручного ввода.

• Умное ранжирование и оценка: оценивает и ранжирует результаты поиска на основе:

  • Качества аудио (MP3 320 kbps, FLAC, V0 и т. д.)

  • Длины очереди (приоритет пирам со свободными слотами загрузки / нулевой очередью)

  • Скорости загрузки пира (в КБ/с)

• Массовая автоматизация (auto_find_and_download): вставьте список песен или альбомов в вашего ИИ-агента; он выполнит поиск, выберет оптимальный файл для каждого и поставит загрузки в очередь автоматически.

• Мониторинг передачи в реальном времени (get_downloads_status): отслеживайте процент выполнения, скорость загрузки и позиции в очереди.

• Высокое качество кода: создан с помощью uv, строгие аннотации типов, схемы Pydantic v2, проверено с помощью ruff и pytest.

Доступные MCP-инструменты

🚀 Настройка за 1 минуту без установки для ИИ-агентов

Вы можете указать любому ИИ-агенту (Claude Desktop, Antigravity, Cursor, Windsurf, Cline, Roo Code и т. д.) напрямую на этот репозиторий GitHub без клонирования и ручного управления виртуальными окружениями.

Рекомендуется: установка без установки через uvx (macOS, Windows, Linux)

Добавьте это в файл настроек MCP (например, 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 автоматически загружает, устанавливает в изолированный кэш и запускает сервер по требованию.

• Вы можете закрепить конкретную версию релиза, добавив @v0.2.0 (рекомендуется для стабильности), или использовать ветку master по умолчанию, чтобы всегда получать последние обновления.

💻 Локальная настройка через Git Clone

Если вы предпочитаете клонировать и запускать сервер локально:

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

Локальная конфигурация 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] Кроссплатформенное автоматическое определение:

• Linux: автоматически использует ~/.config/nicotine/config и $XDG_DATA_HOME/nicotine.

• macOS: автоматически проверяет ~/Library/Application Support/nicotine и ~/.config/nicotine.

• Windows: автоматически использует %APPDATA%\nicotine\config.

Если вы уже используете десктопное приложение Nicotine+ на своём компьютере, настройка или учётные данные не требуются. Если вы хотите указать собственные учётные данные или пути, просто добавьте SOULSEEK_USERNAME, SOULSEEK_PASSWORD и SOULSEEK_DOWNLOAD_DIR в блок env.

Пример использования с вашим ИИ-агентом

Вы можете вставить запросы, например:

«Пожалуйста, найдите и загрузите следующие треки в MP3 320kbps, выбирая самых быстрых пиров со свободными слотами загрузки:

1. Daft Punk - Around the World

2. Aphex Twin - Xtal

3. Boards of Canada - Dayvan Cowboy»

Агент выполнит auto_find_and_download со списком, и вы сможете в любой момент проверить ход выполнения, спросив «Как там мои загрузки?» (это вызовет get_downloads_status).

Разработка, тестирование и проверка

Запуск всех тестовых наборов:

uv run pytest

Запуск линтера кода и проверки форматирования (ruff):

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

Строгая проверка типов с помощью ty:

uv run ty check src/nicotine_mcp tests

Аудит зависимостей на наличие уязвимостей безопасности и целостность lock-файла:

uv run pip-audit
uv lock --check