slsk-mcp
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., "@slsk-mcp find and download Kind of Blue by Miles Davis in FLAC"
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.
slsk-mcp
A Model Context Protocol server that gives any MCP-capable AI assistant the ability to log in to Soulseek, search the network, and download files — all through simple tool calls.
Built on aioslsk 1.4.x.
Quick Start
# Install dependencies
uv sync
# Run the server (stdio transport)
uv run python -m slsk_mcp.serverRelated MCP server: mcp-slskd
Environment Variables
Variable | Default | Description |
| — | Auto-login username |
| — | Auto-login password |
|
| Default download directory |
| aioslsk default | Soulseek listening port |
| aioslsk default | Obfuscated port |
|
| Seconds to wait for search results |
|
| Parallel download limit |
|
| Parallel search ticket limit |
|
| Max simultaneous socket operations |
MCP Integration
Add to your MCP config (e.g. Windsurf global settings or ~/.cursor/mcp.json).
Option A — Install from GitHub (no clone needed)
{
"mcpServers": {
"slsk": {
"command": "uvx",
"args": ["--from", "git+https://github.com/voidtype/slsk_mcp.git", "slsk-mcp"],
"env": {
"SLSK_USERNAME": "your_username",
"SLSK_PASSWORD": "your_password",
"SLSK_DOWNLOAD_DIR": "/home/you/music"
}
}
}
}Option B — Local clone
git clone https://github.com/voidtype/slsk_mcp.git{
"mcpServers": {
"slsk": {
"command": "uv",
"args": ["run", "--directory", "/path/to/slsk_mcp", "slsk-mcp"],
"env": {
"SLSK_USERNAME": "your_username",
"SLSK_PASSWORD": "your_password",
"SLSK_DOWNLOAD_DIR": "/home/you/music"
}
}
}
}Option C — pip install from GitHub
pip install git+https://github.com/voidtype/slsk_mcp.git{
"mcpServers": {
"slsk": {
"command": "slsk-mcp",
"env": {
"SLSK_USERNAME": "your_username",
"SLSK_PASSWORD": "your_password",
"SLSK_DOWNLOAD_DIR": "/home/you/music"
}
}
}
}Tools
Tool | Description |
| Search the network for files |
| Download a file from a peer |
| Poll download progress |
| Abort an in-progress download |
| Check a peer's online status, speed, queue, and free slots |
Resources
URI | Description |
| Connection state, username, passive mode |
| All tracked downloads with progress |
| Actionable search & download strategies (sourced from Nicotine+, sldl, Soularr, SoulSync) |
Tips & Tricks
Soulseek is a peer-to-peer network — every file lives on someone else's machine. These strategies are drawn from how Nicotine+, sldl, Soularr, and SoulSync handle search and download.
Tip: These strategies are also available as structured data via the
slsk://search_tipsresource endpoint — designed for AI agents to read programmatically.
Search Query Craft
Soulseek search works by tokenizing your query and matching against every shared filename and folder path on connected peers. The server-side algorithm is a simple word-intersection: every word you send must appear somewhere in the file's path for it to match.
Provide the least input that uniquely identifies the file.
"Miles Davis Kind of Blue flac"is better than"jazz trumpet classic album". Include artist + album + format when known. (sldl docs: "always best to provide the least input necessary to uniquely identify an album or song")Exclude junk with
-(minus). Nicotine+ supportsflac -liveto exclude live recordings, orjazz -compilationto skip compilations. The Soulseek protocol supports excluded terms — include-termdirectly in the query string. (Nicotine+ search syntax docs)Search matches folder names and full file paths, not just filenames. Searching
"experimental"returns all files inside folders named "experimental". You can search by genre folder names, label names, or any part of the directory structure. (Soulseek Wikipedia)Drop "feat." and featured artists from queries. Tools like sldl strip these with
--remove-ftbecause featured artist credits vary wildly across file names and cause missed matches.For "Various Artists" compilations, search by track name, not artist. The artist field on compilations is unreliable. sldl recommends removing the artist entirely for VA releases.
Partial matching with
*works only at the start of a word in Nicotine+.*trancematches "psytrance" butremix*does not work. Keep this in mind if searches seem to miss results.
Search Filters
All filters are applied post-search on the result set, the same way Nicotine+, sldl, and Soularr implement them. They're available as params on the search tool:
Param | Type | Source | Example |
|
| Nicotine+ file type filter, Soularr |
|
|
| sldl |
|
|
| Nicotine+ min file size filter |
|
|
| Nicotine+ max file size filter |
|
|
| Nicotine+ "Free Slot" filter (most impactful for reliability) |
|
|
| Soularr |
|
|
| Soularr |
|
Note on min_bitrate: Files with unknown bitrate are kept, not rejected. The standard SoulseekQt client does not broadcast bitrate info, so rejecting unknowns would exclude many valid files. This matches sldl's behavior. (sldl docs on --strict-conditions caveat)
Timeout & Timing
7 seconds is the minimum, not the ideal. For popular music 7–10s is fine. For rare/obscure content, use
timeout=20ortimeout=30. sldl's--fast-searchmode exits early when a good match is found, but for broad discovery you want a longer window.Search results are a snapshot of who's online right now. Different peers are online at different times of day. Nicotine+'s wishlist feature re-runs searches every 90–120 minutes for this reason. If you don't find something, try again later.
Peak hours yield more results. The Nicotine+ docs note that searching during peak hours (evenings in the US/EU) means more peers online and more results. Off-peak searches for niche content may come back empty.
Choosing Peers (the key to avoiding "stuck at queued")
This is the single most important part. A file appearing in search results does not mean the peer will serve it to you. Tools like Soularr and SoulSync score peers before downloading.
has_free_slots: trueis the #1 signal. Nicotine+ lets you filter results to only show users with free upload slots. Usefree_slots_only=trueon search, or check the field in results. Ifhas_free_slotsisfalse, you'll sit in their queue — potentially for hours.Check
queue_size. Soularr rejects peers with queue sizes above a threshold (maximum_peer_queue = 50by default). Usemax_queue_size=50on search to apply the same filter.Check
avg_speed. Soularr sets aminimum_peer_upload_speedfloor. Usemin_speed=50000to filter. But remember: your actual download speed is the slowest link between you and the peer (WikiHow Soulseek guide). Use speed as a tiebreaker, not a guarantee.Use
peer_statusbefore committing. The peer was online during search but may have gone offline since.peer_status(username)queries their current state from the server — check forstatus: "online"andhas_slots_free: truebefore downloading.For full albums, pick one peer for all tracks. SoulSync calls this "source reuse for album consistency" — downloading an entire album from the same user ensures consistent encoding, tagging, and folder structure rather than getting a Frankenstein album from 12 different rippers.
Some peers can't connect to you (and vice versa). If you're behind NAT and so is the peer, neither side can initiate a direct connection. This is the most common cause of permanent "queued" with no position number. The only fix is to try a different peer. (Soulseek FAQ)
Downloading Strategies
Stuck at "queued" with no queue position? This almost always means a connectivity issue — the peer can't reach you, or you can't reach them. Cancel and try the next peer sharing the same file. (r/Soulseek: common advice across dozens of "stuck at queued" threads)
Set a stale timeout. Soularr uses
stalled_timeout = 3600(1 hour) to abort downloads that aren't progressing. sldl uses--max-stale-time 30for faster iteration. Polldownload_statusperiodically; ifprogress_pcthasn't moved, callcancel_downloadand retry from the next peer.Don't be afraid to cancel and retry from a different peer. The same file is usually shared by dozens of users. Canceling a stalled download and picking the next result is the standard workflow in every Soulseek client.
For quality, prefer FLAC but accept fallbacks. sldl's default strategy is to prefer lossless (
pref-format = flac,wav) but still accept lossy if lossless isn't available, with a minimum bitrate preference of 200 kbps. Search first withextensions=["flac"]; ifcount=0, retry withextensions=["flac","mp3"].Don't queue tons of files from one user. Soulseek etiquette: stick to 1–2 albums at a time per user. Queuing too much may get you banned. Spread downloads across multiple peers. (WikiHow ban avoidance guide)
Passive mode is normal. If you're behind NAT without port forwarding, the server falls back to passive mode. Downloads still work but are relay-negotiated. Some very old clients may not support it. UPnP can help if your router supports it (WikiHow).
Troubleshooting
Empty search results? Check: (1) query too specific — try fewer words, (2) timeout too short — increase to 15–20s, (3) search term matches an excluded phrase, (4) very few peers share this content — try again at peak hours. (Nicotine+ troubleshooting)
"Login failed" on startup? Credentials wrong, or
server.slsknet.orgtemporarily down. VerifySLSK_USERNAME/SLSK_PASSWORD. Note: Soulseek recycles usernames after 30 days of inactivity. (Soulseek FAQ)Everything is slow? Increase
SLSK_MAX_CONCURRENT_DLto download from more peers in parallel. Close other bandwidth-heavy apps. If your upload is saturated (someone downloading from you), it can throttle your downloads too.Getting banned? Some users ban leechers. The Soulseek community expects you to share files back. Users with no shared files or very slow upload speeds may be deprioritized or banned by individual peers. (WikiHow)
Development
uv sync --extra dev
uv run pytestAvailable Tools
8 toolscancel_downloadA
Abort an in-progress download.
ONLY cancel a download if:
download_status shows age_seconds > 180 AND status is still 'queued' (stuck)
download_status shows status='failed'
You explicitly want to switch to a different peer
Do NOT cancel just because progress is 0% — P2P connections take 1-3 minutes.
Inputs: id (required).
connection_healthA
Check the MCP's Soulseek connection health before starting work.
Call this at the start of every session and after any suspected restart. Returns: connected, passive_mode, session_id, listening_port, p2p_reachable, session_uptime_secs, active_downloads, and a note if something needs attention.
Key fields:
session_id: increments on each login. If it changed since your last check, all previous download IDs are invalid — re-search and re-download.
p2p_reachable: false means downloads will likely fail (double-NAT). Warn the user and suggest configuring SLSK_LISTEN_PORT + port forwarding.
passive_mode: true means no listening port bound. Same implication as above.
Inputs: no named parameters.
downloadA
Download a file from a Soulseek peer.
Files are saved to the directory configured by SLSK_DOWNLOAD_DIR.
IMPORTANT: After calling this, SLEEP for at least 30 seconds (or do other productive work) before calling download_status. P2P connections take time to establish — the peer must accept, negotiate, and begin sending data. Checking immediately wastes tokens and will always show 0%.
The response includes wait_before_poll_secs — you MUST sleep/wait that many seconds before your first status poll. Do not live-poll in a loop.
Inputs: id (required).
download_statusA
Poll progress of an active or recent download.
CRITICAL TIMING RULES:
Do NOT call this within 30 seconds of starting a download.
status='queued' at 0% is NORMAL for the first 1-2 minutes. P2P takes time.
Do NOT cancel a download just because it shows queued/0%. Check age_seconds.
Only consider cancelling if age_seconds > 180 (3 minutes) with no progress.
The 'message' field contains contextual guidance — READ IT and follow its sleep recommendation before polling again. Do NOT live-poll in a tight loop.
If status='not_found' or status='session_expired', the download ID is stale (server restarted). You must re-search and re-download.
Inputs: id (required).
get_configA
Return the MCP's runtime configuration (no secrets).
Use this to check where files are being downloaded, which ports are configured, concurrency limits, and the connected username.
Inputs: no named parameters.
list_downloadsA
List all active/queued/recent downloads in the current session.
Use this to recover state after context compaction or session resume. Returns all tracked downloads with their current status, progress, age_seconds, username, connection_state, and local_path.
Each entry includes the download ID so you can call download_status or cancel_download on specific items.
Inputs: no named parameters.
peer_statusA
Check a peer's online status, speed, queue, and free slots before downloading.
Inputs: username (required).
searchA
Search the Soulseek network for files.
Filters (applied post-search, like Nicotine+/sldl/Soularr):
extensions: only return files with these extensions (e.g. ["flac","mp3"])
min_bitrate: minimum bitrate in kbps (files with unknown bitrate are kept)
min_filesize / max_filesize: file size bounds in bytes
free_slots_only: only return results from peers with free upload slots
max_queue_size: skip peers with queue larger than this (Soularr default: 50)
min_speed: minimum peer upload speed in bytes/sec
Inputs: query (required), timeout, min_speed, extensions, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct capability: search finds files, download initiates transfers, download_status polls progress, cancel_download aborts, list_downloads enumerates active sessions, connection_health checks connectivity, peer_status inspects peer state, and get_config retrieves settings. There is no functional overlap between any two tools.
All names use lowercase_snake_case, but the pattern mixes single verbs (search, download) with verb_noun (get_config, cancel_download, list_downloads) and noun phrases (connection_health, peer_status, download_status). While readable and predictable, it is not a strict verb_noun convention throughout.
Eight tools is well within the ideal 3-15 range and is appropriate for a focused Soulseek client. Each tool earns its place, covering search, download lifecycle, session management, and health checks without unnecessary bloat.
The tool surface covers the full download workflow: search, initiate download, poll status, cancel, and list active/recent transfers. It also includes connection health, peer status, and config retrieval to address operational concerns. No obvious dead ends or missing core operations for a download-centric Soulseek MCP.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
AI tool directory MCP server, live since July 2026. Tools, agents, models, companies, services.
MCP server for Producer/Riffusion AI music generation
Web search API and MCP server for developers building AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents the ability to listen to and understand music/audio files, enabling semantic analysis, stem separation, lyrics transcription, and signal processing via tool calls.1MIT
- FlicenseAqualityDmaintenanceMCP server for searching and downloading music from the Soulseek peer-to-peer network via slskd. Enables AI assistants to discover and download music directly.5-
- 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
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to search and download music from the Soulseek peer-to-peer network via Nicotine+, with smart ranking of results by audio quality and peer speed, bulk automation, and real-time transfer monitoring.-