# Nicotine+ Soulseek MCP Server

A stateless, local-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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

| Tool Name | Description |
| --- | --- |
| `search_tracks` | Searches Soulseek for tracks/albums with filters for bitrate (default 320 kbps), file type (`mp3`, `flac`, etc.), max queue, and free slots. Results are scored and sorted by quality & speed. |
| `auto_find_and_download` | **Bulk track finder**: Takes a list of song/album queries, searches Soulseek for each, picks the best candidate meeting quality (default 320 kbps) & queue criteria, and enqueues downloads. |
| `queue_download` | Enqueues a specific file for download using its username and virtual path from search results. |
| `get_downloads_status` | Returns real-time status, progress percentages, speeds, and queue positions for all active, queued, and completed downloads. |
| `clear_finished_downloads` | Clears finished transfers from the download list. |
| `get_connection_status` | Returns connection state, logged-in user, server address, and download destination path. |
| `set_credentials` | Sets or updates Soulseek username and password dynamically. |

## 🚀 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`):

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

> [!TIP]
>
> - `uvx` automatically downloads, installs in an isolated cache, and launches the server on demand.
> - You can pin a specific release version by adding `@v0.2.0` (recommended for stability) or use the default `master` branch to always get the latest updates.

---

## 💻 Local Git Clone Setup

If you prefer to clone and run the server locally:

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

### Local MCP Configuration

#### macOS / Linux

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

#### Windows

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

> [!NOTE]
> **Cross-Platform Auto-Detection**:
>
> - **Linux**: Automatically uses `~/.config/nicotine/config` and `$XDG_DATA_HOME/nicotine`.
> - **macOS**: Automatically checks `~/Library/Application Support/nicotine` and `~/.config/nicotine`.
> - **Windows**: Automatically uses `%APPDATA%\nicotine\config`.
>
> If you already use the Nicotine+ desktop app on your machine, zero setup or credentials are required. If you want to specify custom credentials or paths, simply add `SOULSEEK_USERNAME`, `SOULSEEK_PASSWORD`, and `SOULSEEK_DOWNLOAD_DIR` to the `env` block.

---

## 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:

```bash
uv run pytest
```

Run code linter & format checker (`ruff`):

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

Run strict type checking with `ty`:

```bash
uv run ty check src/nicotine_mcp tests
```

Audit dependencies for security vulnerabilities & lockfile integrity:

```bash
uv run pip-audit
uv lock --check
```