Slskd

An MCP (Model Context Protocol) server that gives AI agents full control over slskd, a modern Soulseek client. Auto-generated from the slskd OpenAPI spec (70 paths, 93 operations).

Built because manually searching Soulseek via podman exec wget chains was costing 60% of our tokens. This gives agents direct access to search, download, browse peers, monitor transfers, and manage the slskd instance — the missing piece in the Lidarr → Soulseek → Plex music pipeline.

This entire project — the generator, the server, the test suite, and this README — was built by AI (Claude) and is designed to be installed and used by AI agents.

Install

Option 1: Nix Flake (recommended)

# flake.nix
{
  inputs.slskd-mcp.url = "github:abl030/slskd-mcp";
}

# Use the package
environment.systemPackages = [ inputs.slskd-mcp.packages.${pkgs.system}.default ];

# Or in an MCP server config
{
  command = "${inputs.slskd-mcp.packages.${pkgs.system}.default}/bin/slskd-mcp";
  env = {
    SLSKD_URL = "http://localhost:5030";
    SLSKD_API_KEY = "your-api-key";
  };
}

Quick test without installing:

SLSKD_URL=http://localhost:5030 SLSKD_API_KEY=your-key nix run github:abl030/slskd-mcp

Option 2: uv (non-Nix)

git clone https://github.com/abl030/slskd-mcp.git
cd slskd-mcp
uv sync
uv run python -m generator    # produces generated/server.py

Configure Your MCP Client

Claude Code:

# Nix
claude mcp add slskd -- \
  env SLSKD_URL=http://YOUR_SLSKD_HOST:5030 \
  SLSKD_API_KEY=YOUR_API_KEY \
  slskd-mcp

# Non-Nix
claude mcp add slskd -- \
  env SLSKD_URL=http://YOUR_SLSKD_HOST:5030 \
  SLSKD_API_KEY=YOUR_API_KEY \
  uv run --directory /path/to/slskd-mcp fastmcp run generated/server.py

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "slskd": {
      "command": "slskd-mcp",
      "env": {
        "SLSKD_URL": "http://YOUR_SLSKD_HOST:5030",
        "SLSKD_API_KEY": "YOUR_API_KEY",
        "SLSKD_MODULES": "searches,transfers,users,files,rooms,server"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
SLSKD_URL	http://localhost:5030	slskd base URL
SLSKD_API_KEY	(required)	API key (Settings > General > API Keys)
SLSKD_MODULES	(all modules)	Comma-separated list of modules to enable
SLSKD_READ_ONLY	false	Strip all mutation tools (POST/PUT/DELETE)

Module Filtering

By default all tools are registered. Set SLSKD_MODULES to load only what you need:

Module	What it covers
searches	Create searches, list results, get responses, delete searches
transfers	Download/upload management, queue downloads, cancel, clear completed
users	Browse peer shares, get user info/status/endpoint, request directories
files	Download/incomplete file management, delete files/directories
conversations	Private messaging — send, read, acknowledge messages
rooms	Chat rooms — join, leave, list, send messages, view members
server	Server state — connect, disconnect, status
application	Application info, version, shutdown, restart, GC, dump
options	Runtime configuration — get/set YAML config
shares	Local share management — list, rescan, get contents
session	Authentication — login, session check
telemetry	Metrics, transfer reports, leaderboards
relay	Relay agent/controller management
events	Server-sent events, raise events
logs	Application logs

slskd_get_overview, slskd_search_tools, and slskd_report_issue are always registered regardless of module selection.

Example configurations:

# Music pipeline (search + download + browse peers)
SLSKD_MODULES=searches,transfers,users,files

# Monitoring only
SLSKD_MODULES=server,transfers,telemetry
SLSKD_READ_ONLY=true

# Full control
# (default — all modules enabled)

What You Get

TODO: Tool counts will be filled after generator Sprint 1 completes.

Category	Examples
Searches	Create search, list active/completed searches, get responses, delete
Transfers	List downloads/uploads, queue download from peer, cancel, clear completed
Users	Browse peer shares, get user info/status, request directory listing
Files	List/delete downloaded files, list/delete incomplete files
Conversations	Send/read private messages, acknowledge messages
Rooms	Join/leave rooms, send messages, list members, available rooms
Server	Connect/disconnect Soulseek, get server state
Shares	List local shares, rescan shares, get share contents
Telemetry	Transfer stats, leaderboards, exception reports

High-Level Tools (no API knowledge needed)

Tool	Description
slskd_get_overview	System summary: server state, transfer counts, search activity
slskd_search_tools	Keyword search across all tool names/descriptions
slskd_report_issue	Generate structured bug report

Safety: Confirmation Gate

All mutations require confirm=True. Without it, you get a dry-run preview:

# Preview only — nothing changes
slskd_create_search(searchText="xaviersobased Xavier")

# Actually creates the search
slskd_create_search(searchText="xaviersobased Xavier", confirm=True)

List Tool Filtering

All slskd_list_* tools support optional parameters:

• fields — Comma-separated field names to return (e.g. "username,state")
• filter — Comma-separated key=value pairs for row filtering (e.g. "state=Completed")

Error Reporting

Every tool's docstring nudges AI consumers to call slskd_report_issue on unexpected errors.

How It Works

A Python generator reads the slskd OpenAPI 3.0.1 spec (70 paths, 93 operations) and produces the MCP server via Jinja2 templates. When slskd updates their API, run a temp container with SLSKD_SWAGGER=true, pull the new spec, and re-run:

# Pull new spec (slskd needs SLSKD_SWAGGER=true to expose it)
docker run -d --name slskd-swagger -e SLSKD_SWAGGER=true -p 15030:5030 slskd/slskd:latest
sleep 5
curl -sf http://localhost:15030/swagger/v0/swagger.json -o spec/openapi.json
docker rm -f slskd-swagger

# Regenerate
nix develop -c python -m generator

The generated server uses FastMCP with a single SlskdClient class (httpx + API key auth via X-Api-Key header). One async tool function per API operation.

Architecture

spec/openapi.json              # slskd OpenAPI 3.0.1 spec (input, 70 paths)
generator/                     # Python generator
  __main__.py                  # Entry point: python -m generator
  loader.py                    # Load and parse the OpenAPI spec
  naming.py                    # Convert method+path to tool names
  schema_parser.py             # Extract parameter types from schemas
  context_builder.py           # Build template context, assign modules
  codegen.py                   # Render templates and write output
templates/
  server.py.j2                 # FastMCP server template
generated/
  server.py                    # The MCP server (never hand-edit)
tests/                         # Unit + integration tests
research/                      # Best practices, API notes

Testing

Unit Tests (no slskd needed)

nix develop -c python -m pytest tests/ -v

Integration Tests (needs slskd)

# Start slskd in Docker
docker compose -f docker/docker-compose.yml up -d

# Wait for ready
bash docker/wait-for-ready.sh

# Run integration tests
nix develop -c python -m pytest tests/test_integration.py -v --integration

# Tear down
docker compose -f docker/docker-compose.yml down

Sprint Plan

Sprint 1: Generator Core

• OpenAPI spec loader (loader.py) — parse paths, operations, schemas
• Naming conventions (naming.py) — method+path to slskd_{verb}_{resource}
• Schema parser (schema_parser.py) — extract parameter types, handle $ref, allOf
• Context builder (context_builder.py) — assign modules, build template context
• Code generator (codegen.py) — render server.py via Jinja2
• Server template (server.py.j2) — FastMCP server with SlskdClient, module gating, confirm gates
• Generate and verify tool count matches spec

Sprint 2: Quality & Correctness

• Apply MCP best practices (see research/mcp-server-best-practices.md)
  • Sanitize large integers (>= 2^53)
  • Exclude readOnly fields from request parameters
  • Enum values in parameter descriptions
  • Strip HTML from descriptions
  • PATCH defaults to None
• List tool enhancements: fields, filter parameters
• High-level tools: slskd_get_overview, slskd_search_tools, slskd_report_issue
• Workflow hints for search → download → import pipeline
• Error wrapping with structured error dicts
• Base64 encoding helper for file/directory path parameters
• Unit tests: naming, modules, list tools

Sprint 3: Integration Testing

• Docker compose for slskd test instance
• Integration tests against live slskd
• Makefile for orchestration
• Nix flake checks with unit tests

Sprint 4: LLM Testing

• Task config and auto-generated task files
• Run bank tests against slskd in Docker
• Docstring improvements from test feedback

Sprint 5: Documentation & Release

• Fill in tool counts in README
• Wire into nixosconfig .mcp.json
• PyPI packaging + MCP Registry submission

slskd-Specific Notes

Authentication

slskd uses API key authentication via X-Api-Key header. The spec doesn't define a security scheme — auth is handled by middleware. Generate an API key in slskd Settings > General > API Keys.

Base64-Encoded Path Parameters

Several file/directory endpoints use base64-encoded path parameters (base64SubdirectoryName, base64FileName). The generator should add a helper that auto-encodes these.

No operationIds in Spec

The slskd spec has no operationId fields — tool names must be derived entirely from HTTP method + path (same approach as lidarr-mcp).

Swagger is a Feature Flag

slskd doesn't expose OpenAPI by default. To regenerate the spec, run slskd with SLSKD_SWAGGER=true (env var) or --swagger (CLI flag).

Key Workflows for Music Pipeline

1. Search and download: slskd_create_search → poll slskd_get_search → browse results via slskd_list_search_responses → slskd_create_transfer_download (queue download from specific peer)
2. Browse peer shares: slskd_get_user_browse → slskd_create_user_directory (get directory listing)
3. Monitor downloads: slskd_list_transfers_downloads → check status → slskd_delete_transfers_downloads_completed (clear finished)

Dependencies

Nix users: nix run github:abl030/slskd-mcp — everything bundled.

Non-Nix users: Python 3.11+, uv, fastmcp, httpx, jinja2 (installed by uv sync).

License

MIT