MCP Soulseek (slskd)

Model Context Protocol (MCP) server for searching and downloading music from the Soulseek peer-to-peer network via 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 instance running and connected to Soulseek
• Python 3.11+

Quick Start

1. Environment

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

2. Run with uv (recommended)

uv run python -m mcp_slskd

3. Run with pip

pip install mcp slskd-api
python -m mcp_slskd

4. Run with Docker

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

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:

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

{
  "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.

License

MIT