Nicotine+ Soulseek MCP Server

A stateless, local-only Model Context Protocol (MCP) server that interfaces directly with the Nicotine+ (Soulseek) network engine.

It allows AI assistants (such as Claude Desktop, Antigravity, or other MCP clients) to search the Soulseek peer-to-peer network, evaluate audio quality/bitrates, select download candidates with the lowest queue and fastest speeds, automatically download bulk tracklists, and monitor transfer progress.

Features

• Local & Stateless: Runs locally over standard STDIO using the official Python MCP SDK.

• Auto-Detects Desktop Nicotine+ Config: Automatically reads your existing desktop Nicotine+ configuration (~/.config/nicotine/config or %APPDATA%/nicotine/config), inheriting your existing Soulseek account and download directories without manual re-entry.

• Smart Ranking & Scoring: Evaluates and ranks search results based on:

  • Audio quality (320 kbps MP3, FLAC, V0, etc.)

  • Queue length (prioritizing peers with free upload slots / 0 queue)

  • Peer upload speed (in KB/s)

• Bulk Automation (auto_find_and_download): Paste a list of songs or albums into your AI agent; it will search, pick the optimal file for each, and enqueue the downloads automatically.

• Real-Time Transfer Monitoring (get_downloads_status): Track progress percentages, download speed, and queue positions.

• High Code Quality: Built with uv, strict type annotations, Pydantic v2 schemas, and verified with ruff and pytest.

Available MCP Tools

🚀 1-Minute Zero-Install Setup for AI Agents

You can point any AI agent (Claude Desktop, Antigravity, Cursor, Windsurf, Cline, Roo Code, etc.) directly to this GitHub repository without cloning or manually managing virtual environments.

Recommended: Zero-Install via uvx (macOS, Windows, Linux)

Add this to your MCP settings file (e.g., claude_desktop_config.json):

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

💻 Local Git Clone Setup

If you prefer to clone and run the server locally:

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

Local MCP Configuration

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"
      ]
    }
  }
}

Example Usage with Your AI Agent

You can paste prompt requests such as:

"Please search for and download the following tracks in 320kbps MP3, picking the fastest peers with free upload slots:

1. Daft Punk - Around the World

2. Aphex Twin - Xtal

3. Boards of Canada - Dayvan Cowboy"

The agent will execute auto_find_and_download with the list, and you can check the progress at any time by asking "How are my downloads going?" (which calls get_downloads_status).

Development, Testing & Verification

Run all test suites:

uv run pytest

Run code linter & format checker (ruff):

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

Run strict type checking with ty:

uv run ty check src/nicotine_mcp tests

Audit dependencies for security vulnerabilities & lockfile integrity:

uv run pip-audit
uv lock --check