mcp-slskd
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-slskd search for 'Bohemian Rhapsody' by Queen"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 for music files on Soulseek |
| Download a file from a user |
| Check progress of active downloads |
| Browse a user's shared files |
| 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"2. Run with uv (recommended)
uv run python -m mcp_slskd3. Run with pip
pip install mcp slskd-api
python -m mcp_slskd4. 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:latestDocker 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:
- slskdMCP 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 API endpoint |
|
| API key (alternative to user/pass) |
|
| slskd web UI username |
|
| 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 toolsbrowse_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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Producer/Riffusion AI music generation
Search and install 4,000+ security-scanned MCP servers from inside any MCP-aware AI client.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
Related MCP Servers
- FlicenseBqualityNot gradedmaintenanceEnables Claude to search and download music files from the Soulseek peer-to-peer network using a Soulseek account.3-
- AlicenseNot gradedqualityDmaintenanceAn 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.2MIT
- FlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to log into Soulseek, search the network, and download files through simple tool calls.85-
- AlicenseAqualityDmaintenanceEnables MCP-compatible agents to search Soulseek and manage authorized downloads through an existing slskd instance.3Creative Commons Zero v1.0 Universal