Nicotine+ Soulseek MCP 서버

Nicotine+ (Soulseek) 네트워크 엔진과 직접 인터페이스하는 무상태(stateless), 로컬 전용 Model Context Protocol (MCP) 서버입니다.

AI 어시스턴트(Claude Desktop, Antigravity 또는 기타 MCP 클라이언트)가 Soulseek P2P 네트워크를 검색하고, 오디오 품질/비트레이트를 평가하고, 대기열이 가장 짧고 속도가 가장 빠른 다운로드 후보를 선택하며, 대량 트랙리스트를 자동으로 다운로드하고, 전송 진행 상황을 모니터링할 수 있게 해줍니다.

기능

• 로컬 및 무상태: 공식 Python MCP SDK를 사용하여 표준 STDIO를 통해 로컬에서 실행됩니다.

• 데스크톱 Nicotine+ 설정 자동 감지: 기존 데스크톱 Nicotine+ 구성(~/.config/nicotine/config 또는 %APPDATA%/nicotine/config)을 자동으로 읽어, 수동 입력 없이 기존 Soulseek 계정과 다운로드 디렉토리를 상속합니다.

• 스마트 순위 및 점수 매기기: 검색 결과를 다음 기준으로 평가하고 순위를 매깁니다:

  • 오디오 품질(320 kbps MP3, FLAC, V0 등)

  • 대기열 길이(업로드 슬롯이 비어 있거나 대기열이 0인 피어 우선)

  • 피어 업로드 속도(KB/s)

• 대량 자동화 (auto_find_and_download): AI 에이전트에 노래 또는 앨범 목록을 붙여넣으면, 각 항목을 검색하고 최적의 파일을 선택하여 자동으로 다운로드를 대기열에 추가합니다.

• 실시간 전송 모니터링 (get_downloads_status): 진행률 퍼센트, 다운로드 속도, 대기열 위치를 추적합니다.

• 높은 코드 품질: uv로 구축되었으며, 엄격한 타입 주석, Pydantic v2 스키마, ruff 및 pytest로 검증되었습니다.

사용 가능한 MCP 도구

🚀 AI 에이전트용 1분 제로 설치 설정

GitHub 저장소를 복제하거나 가상 환경을 수동으로 관리하지 않고도 어떤 AI 에이전트(Claude Desktop, Antigravity, Cursor, Windsurf, Cline, Windsurf 등)에 이 서버를 직접 연결할 수 있습니다.

권장: 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 클론 설정

서버를 직접 클론하여 로컬에서 실행하려면:

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+ 데스크톱 앱을 사용 중이라면 설정이나 자격 증명이 필요하지 않습니다. 사용자 지정 자격 증명이나 경로를 지정하려면 env 블록에 SOULSEEK_USERNAME, SOULSEEK_PASSWORD, SOULSEEK_DOWNLOAD_DIR을 추가하기만 하면 됩니다.

AI 에이전트와 함께 사용하는 예시

다음과 같은 프롬프트 요청을 붙여넣을 수 있습니다:

"다음 트랙을 320kbps MP3로 검색하여 다운로드해 주세요. 업로드 슬롯이 비어 있는 가장 빠른 피어를 선택하세요:

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

의존성 감사 및 무결성 확인:

uv run pip-audit
uv lock --check