# MCP Soulseek (slskd)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Model Context Protocol (MCP) server for searching and downloading music from the [Soulseek](https://www.slsknet.org/) peer-to-peer network via [slskd](https://github.com/slskd/slskd).

This server exposes Soulseek's search and download capabilities as MCP tools, allowing AI assistants (Claude, Hermes, etc.) to discover and download music directly.

## Tools

| Tool | Description |
|------|-------------|
| `search_music(query, limit)` | Search for music files on Soulseek |
| `download_music(username, filename, size)` | Download a file from a user |
| `download_status()` | Check progress of active downloads |
| `browse_user(username)` | Browse a user's shared files |
| `search_last_results(query)` | Get cached results from last search |

## Prerequisites

- [slskd](https://github.com/slskd/slskd) instance running and connected to Soulseek
- Python 3.11+

## Quick Start

### 1. Environment

```bash
export SLSKD_HOST="http://localhost:5030"
export SLSKD_USER="slskd"
export SLSKD_PASS="slskd"
```

### 2. Run with uv (recommended)

```bash
uv run python -m mcp_slskd
```

### 3. Run with pip

```bash
pip install mcp slskd-api
python -m mcp_slskd
```

### 4. Run with Docker

```bash
docker run -e SLSKD_HOST=http://host.docker.internal:5030 \
  -e SLSKD_USER=slskd \
  -e SLSKD_PASS=slskd \
  ghcr.io/ldgnu/mcp-slskd:latest
```

## Docker Compose

```yaml
services:
  slskd:
    image: slskd/slskd:latest
    ports:
      - "5030:5030"
    volumes:
      - ./slskd_data:/app/data

  mcp-slskd:
    image: ghcr.io/ldgnu/mcp-slskd:latest
    environment:
      SLSKD_HOST: "http://slskd:5030"
      SLSKD_USER: "slskd"
      SLSKD_PASS: "slskd"
    depends_on:
      - slskd
```

## MCP Client Configuration

### Hermes Agent

Add to your `config.yaml`:

```yaml
mcp_servers:
  slskd:
    command: docker
    args: [run, -i, --rm, --network=host,
      -e, SLSKD_HOST=http://localhost:5030,
      -e, SLSKD_USER=slskd,
      -e, SLSKD_PASS=slskd,
      ghcr.io/ldgnu/mcp-slskd:latest]
```

### Claude Desktop

```json
{
  "mcpServers": {
    "soulseek": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network=host",
        "-e", "SLSKD_HOST=http://localhost:5030",
        "-e", "SLSKD_USER=slskd",
        "-e", "SLSKD_PASS=slskd",
        "ghcr.io/ldgnu/mcp-slskd:latest"
      ]
    }
  }
}
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `SLSKD_HOST` | `http://127.0.0.1:5030` | slskd API endpoint |
| `SLSKD_API_KEY` | `""` | API key (alternative to user/pass) |
| `SLSKD_USER` | `slskd` | slskd web UI username |
| `SLSKD_PASS` | `slskd` | slskd web UI password |

> **Note**: Change default credentials in production. slskd uses token-based auth internally.

## API

This server wraps the [slskd REST API](https://slskd-api.readthedocs.io/en/latest/api.html).

## License

MIT