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.server

Environment Variables

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

Resources

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_tips resource 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+ supports flac -live to exclude live recordings, or jazz -compilation to skip compilations. The Soulseek protocol supports excluded terms — include -term directly 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-ft because 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+. trance` matches "psytrance" but `remix` 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:

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=20 or timeout=30. sldl's --fast-search mode 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: true` is the #1 signal. Nicotine+ lets you filter results to only show users with free upload slots. Use free_slots_only=true on search, or check the field in results. If has_free_slots is false, you'll sit in their queue — potentially for hours.
• Check `queue_size`. Soularr rejects peers with queue sizes above a threshold (maximum_peer_queue = 50 by default). Use max_queue_size=50 on search to apply the same filter.
• Check `avg_speed`. Soularr sets a minimum_peer_upload_speed floor. Use min_speed=50000 to 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_status` before committing. The peer was online during search but may have gone offline since. peer_status(username) queries their current state from the server — check for status: "online" and has_slots_free: true before 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 30 for faster iteration. Poll download_status periodically; if progress_pct hasn't moved, call cancel_download and 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 with extensions=["flac"]; if count=0, retry with extensions=["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.org temporarily down. Verify SLSK_USERNAME/SLSK_PASSWORD. Note: Soulseek recycles usernames after 30 days of inactivity. (Soulseek FAQ)
• Everything is slow? Increase SLSK_MAX_CONCURRENT_DL to 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 pytest