slskd-mcp
This server lets an AI agent search and download music from the Soulseek P2P network through a local slskd daemon, with standing wishlist monitoring and download management.
Search the network by query (
search) and fetch results asynchronously (search_results), optionally filtering by format (e.g. FLAC, MP3).Search by record label (
search_label) — runs a search and keeps only releases whose folder contains the label as a bracketed tag, avoiding coincidental word matches.Manage a wishlist of standing searches (
wishlist_add,wishlist_list,wishlist_remove) and run checks now (wishlist_check) to see only newly appeared results.List recent searches and their state (
searches).Browse a user's shared files (
browse) by username.View current downloads and progress (
downloads).Queue a download (
download) using exact username, filename and size from search results — requires the server to be started with downloads enabled.Check status of an individual download (
download_status) via username and transfer id.Cancel a download (
cancel_download) — always available, even when downloads are disabled, since it only reduces activity.
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., "@slskd-mcp search Planet Rhythm label for lossless files"
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.
slskd-mcp
⚠️ Work in progress. Works against the live Soulseek network, but APIs will change without warning. No releases, no stability promises.
An MCP server that gives an AI agent structured access to the Soulseek network, via a local slskd daemon.
Searching Soulseek by hand is fine. Searching it systematically — say, working through a list of three hundred record labels and asking which have anything shared in lossless — is exactly the sort of tedious, repetitive lookup an agent should do for you. That's what this is for.
What makes it more than an API wrapper
A label filter that actually works. Soulseek search is a plain substring match over the
whole path, so searching Planet Rhythm returns Leftfield's Phat Planet from Rhythm &
Stealth, plus a pile of Strictly Rhythm house records. The words match; the label doesn't.
Releases are near-universally foldered with the label as a bracketed tag —
Artist - Title EP [Planet Rhythm] — so search_label keeps only paths carrying that tag.
Measured against the live network:
plain search: 250 responders, 1,912 files
label filter: 29 responders, 846 files
+ lossless: 5 responders, 180 filesMatching uses a normalised form (lowercase, alphanumeric only), so [planet rhythm ],
[PLANET-RHYTHM] and [Planet Rhythm 2025] all match while [Strictly Rhythm] does not.
A wishlist that stays quiet. Standing searches re-run and report only results not seen before. Soulseek is a live network of people's hard drives — the record you want may simply not be shared today and may appear next week. A watcher that reported the same eighty-five files every morning would be muted within a week, so it doesn't.
Format filtering with lossless / lossy shorthands, because "is this on the network in
FLAC" is the question that usually matters.
Related MCP server: Soulseek MCP
Tools
tool | kind | what it does |
| read | start a search, return its id |
| read | results for an id, optional format filter |
| read | search a label, keep only genuine releases on it |
| read | list recent searches |
| read | browse a user's shares |
| read | current transfer state |
| write | add a standing search |
| read | show the wishlist |
| write | drop an entry |
| write | run all entries, report only what's new |
| read | one transfer: state, progress, queue position |
| write | queue a transfer — disabled by default |
| write | stop a transfer — always available, see below |
Tool annotations
Every tool declares MCP ToolAnnotations, so a client can tell looking from touching
without being told. Without them a client must assume the worst and prompt before each
call, which makes routine searching unusable.
Ten tools are readOnlyHint. wishlist_add and wishlist_remove write to a local file
and say so. wishlist_check is not read-only despite mostly searching — it records what
it reported, which is the whole point of it. download and cancel_download are writes.
openWorldHint is true on anything touching the network: these are strangers' machines,
not a closed set.
Downloads are gated on purpose
download writes files to disk and generates traffic on a P2P network under the operator's
account. That is categorically different from every read tool, so the server refuses it unless
started with --allow-downloads (or SLSKD_ALLOW_DOWNLOADS=1).
Handing an agent the ability to pull files is a decision someone should make deliberately, not a default nobody reviewed.
cancel_download is deliberately not gated. It only ever reduces activity, and a stop button
you can't reach is not a stop button.
Usage
export SLSKD_URL=http://localhost:5030
export SLSKD_API_KEY=… # from slskd.yml → web.authentication.api_keys
uvx --from . slskd-mcp # stdio MCP server, downloads disabled
slskd-mcp --allow-downloads # opt in to queuing transfers
slskd-mcp --wishlist-run # scheduled mode: prints new results, silent otherwiseAs an MCP server entry:
{
"mcpServers": {
"slskd": {
"command": "slskd-mcp",
"env": {
"SLSKD_URL": "http://localhost:5030",
"SLSKD_API_KEY": "…"
}
}
}
}An API key in slskd's slskd.yml:
web:
authentication:
api_keys:
mcp:
key: <16-255 chars>
role: administrator
cidr: 127.0.0.1/32,::1/128Wishlist state lives at ~/slskd/wishlist.json, overridable with SLSKD_WISHLIST.
Development
uv sync
uv run pytest # 36 tests, no network requiredRequires Python 3.11+. Two dependencies: mcp and httpx2,
which mcp pulls in anyway — so nothing is installed that wouldn't be there regardless.
Note that mcp 2.x renamed FastMCP to MCPServer and ships httpx2 rather than httpx;
most tutorials still show the v1 API.
Platforms
Pure Python, no platform-specific APIs. The home directory is resolved from HOME or
USERPROFILE, so the wishlist lands somewhere sensible on Windows, and path splitting handles
both separators — Soulseek paths use backslashes regardless of the sharing peer's OS.
Only Linux is actually tested.
Notes on slskd's OpenAPI spec
Six findings, recorded so they don't cost anyone else the time they cost here:
The spec is at
/swagger/v0/swagger.json—v0, notv1. Enable theswaggerfeature.14 paths contain a literal
v{version}placeholder — the ASP.NET route template isn't substituted during generation. It affectssearchesandtransfers, so a generated client emits URLs that 404. They resolve tov0at runtime.components.securitySchemesis empty, so a generated client won't attachX-API-Keyor a bearer token.The search endpoints declare no response schemas at all.
POST transfers/downloads/{username}isdeprecated: true— summary reads "(Obsolete)". The live replacement isPOST transfers/downloads/batches, which also carries asearchIdlinking a download back to the search that produced it. This project uses the batch form.That batch endpoint returns
200when every download failed —201is full success and207is partial. A client that treats 2xx as success reports the exact opposite of what happened, soenqueuereturns the status alongside the body and the caller readsfailures.
None of this is a complaint about slskd, which is excellent; it's just what's true of the
generated spec. It is why client.py is hand-written: fighting the generator cost more than
writing a hundred lines of httpx calls.
If you want a fuller Python client — rooms, shares, conversations — use
slskd-api, which is more complete than this
and actively maintained. It is AGPL-3.0, so it isn't used here.
Background: why there's no browser client
This began as "can Soulseek be rewritten in WebAssembly and run in the browser?" It can't, and the reason is worth recording.
WebAssembly has no syscalls of its own. It inherits whatever the host offers, and in a
browser that host is the JS sandbox: fetch, WebSocket, WebRTC, WebTransport — never a raw TCP
socket. Soulseek needs raw TCP twice: to the server (server.slsknet.org:2242, a bespoke
binary protocol) and directly between peers for searches, browsing and every transfer.
The peer half is decisive. Browsers cannot accept inbound connections, and the existing client population speaks TCP rather than WebRTC — a WebRTC mesh would be a new network with no users.
So a browser client needs a local process holding the sockets, which is what slskd already is.
The parked Rust client
crates/slskd-client is a typed Rust HTTP client for the same API, left here because it
compiles for wasm32-unknown-unknown and so keeps a browser front-end possible if that ever
becomes interesting. It is parked, not planned, and nothing in the MCP server depends on
it. The Rust MCP server it once accompanied was replaced by this Python one and lives in git
history.
Roadmap
Group results by release folder rather than listing files
Typed models for
browseanddownloads(currently raw JSON)Better handling of short, generic label names, which collide with unrelated tags
Licence
MIT.
This project only talks to slskd, which is AGPL-3.0.
Nothing from slskd is vendored or linked — client.py speaks to its public HTTP API over the
network, which is the boundary AGPL doesn't reach across.
That is also why the slskd-api package isn't used despite being the better client: it is
AGPL, and depending on it would make this AGPL too.
Available Tools
13 toolsbrowseA
Browse everything a Soulseek user is sharing
Inputs: username (required). Returns: result
cancel_downloadA
Cancel a download in progress. Always available, even when downloads are disabled — stopping a transfer only ever reduces activity.
Inputs: id (required), username (required), remove. Returns: result
downloadA
Queue a file for download. Requires the server to have been started with downloads enabled. Use the exact filename and size from search_results.
Inputs: size (required), filename (required), username (required), search_id. Returns: result
downloadsA
Show current downloads and their progress
Inputs: no named parameters. Returns: result
download_statusA
Check one download: state, percent complete and position in the peer's queue. Needs the username and transfer id from download or downloads.
Inputs: id (required), username (required). Returns: result
searchA
Search the Soulseek network. Returns a search id; results arrive asynchronously, so call search_results a few seconds later.
Inputs: query (required). Returns: result
searchesA
List recent searches and their state
Inputs: no named parameters. Returns: result
search_labelA
Find releases on a specific record label. Runs a search, waits for responses, then keeps only files whose folder carries the label as a bracketed tag (e.g. "... [Planet Rhythm]"). Filters out coincidental word matches, which plain search returns in bulk.
Inputs: label (required), formats. Returns: result
search_resultsB
Get results for a search id. Lists peers and their files with size and bitrate. Use the exact filename and size when downloading.
Inputs: id (required), formats. Returns: result
wishlist_addA
Add a standing search to the wishlist. Wishlist entries are re-run on a schedule and only NEW results are reported, so you hear about a record the week it finally appears on the network.
Inputs: query (required), formats, label_filter. Returns: result
wishlist_checkA
Run all wishlist searches now and report only results not seen before. Takes ~20s per entry because Soulseek results arrive asynchronously.
Inputs: no named parameters. Returns: result
wishlist_listA
List standing wishlist searches
Inputs: no named parameters. Returns: result
wishlist_removeA
Remove a wishlist entry by its 1-based index from wishlist_list
Inputs: index (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools are clearly separated by lifecycle stage or resource: search returns an id, search_results fetches results, searches lists past searches, and search_label is specialized filtering. The only real ambiguity risk is download vs downloads, but the descriptions make the verb/noun distinction clear.
All names use lowercase snake_case, but the pattern is mixed: action-only verbs like search and browse, plural nouns like searches and downloads, noun_verb forms like wishlist_add, and noun_noun compounds like search_results and download_status. The names are readable, but there is no single predictable convention.
13 tools is well within the ideal range and each tool maps to a distinct workflow area: searching, wishlist management, browsing, and download management. Nothing feels redundant or like filler.
The core Soulseek workflow is fully covered: search produces an id, results are fetched, files can be downloaded, progress is tracked, and downloads can be cancelled. Wishlist entries also have complete add/list/remove/manual-check coverage, with no obvious dead ends.
Maintenance
Related MCP Connectors
Music industry tools for AI agents: artist research, catalogs, release plans and content.
The media memory layer for AI agents and their humans. Your AI client can search your collection, add and log what you've finished, update ratings and lists, and find patterns across everything you've read, watched, played, and listened to.
AI music and podcast platform for autonomous agents. SoundCloud for AI bots.
The media station for AI agents: buy, rent and stream music. Artists are paid directly, no pooling.
91
Related MCP Servers
- FlicenseBqualityNot gradedmaintenanceEnables Claude to search and download music files from the Soulseek peer-to-peer network using a Soulseek account.3-
- FlicenseNot gradedqualityBmaintenanceEnables interaction with the Soulseek peer-to-peer file sharing network for searching files, browsing user shares, and managing downloads. Supports chat functionality including public rooms, private messages, and user monitoring.-
- 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-
- 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.-