Skip to main content
Glama
mcp-slskd
by ldgnu

MCP Soulseek (slskd)

License: MIT

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

Related MCP server: slskd-mcp

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

Available Tools

5 tools
browse_userA
Browse a Soulseek user's shared files.

Args:
    username: Soulseek username to browse

Returns:
    List of directories and files shared by the user

Inputs: username (required). Returns: result

download_musicA
Download a file from a Soulseek user.

Args:
    username: Soulseek username who has the file
    filename: Full filename path as returned by search
    size: File size in bytes

Returns:
    Status message

Inputs: filename (required), username (required), size. Returns: result

download_statusA
Check status of active downloads.

Returns:
    List of active/queued downloads with progress

Inputs: no named parameters. Returns: result

search_last_resultsA
Get cached results from the last search for a query.

Args:
    query: The search text used previously

Returns:
    Cached results, or empty list if not found

Inputs: query (required). Returns: result

search_musicA
Search for music files on Soulseek.

Args:
    query: Search text (artist, track, album)
    limit: Max results to return (default 20)

Returns:
    List of search results with username, filename, size, etc.

Inputs: query (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    Tools are mostly distinct: browse_user explores a user's files, search_music performs a new search, download_music starts a download, download_status checks progress, and search_last_results fetches cached results. The only potential confusion is between search_music and search_last_results, but descriptions clarify that one performs a new query and the other retrieves previous results.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (browse_user, search_music, download_music, download_status, search_last_results). The pattern is predictable and readable, with no mixed conventions.

    Tool Count5/5

    Five tools is well-scoped for a music download client, covering the essential actions (search, browse, download, status) without unnecessary redundancy. The count feels appropriate for the domain.

    Completeness4/5

    The core workflow is covered: search for music, browse user shares, download files, and check download status. However, missing operations like cancel or pause downloads represent a minor gap that agents may need to work around, though not critical for basic usage.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI agents full control over slskd, a modern Soulseek client, enabling search, download, browse peers, monitor transfers, and manage the slskd instance.
      2
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to log into Soulseek, search the network, and download files through simple tool calls.
      8
      5
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP-compatible agents to search Soulseek and manage authorized downloads through an existing slskd instance.
      3
      Creative Commons Zero v1.0 Universal