Slskd MCP

slskd MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够完全控制 slskd，现代Soulseek客户。根据slskd OpenAPI规范自动生成（70条路径，93次操作）。

由于通过手动搜索Soulseek而构建 podman exec wget 链条是 花费我们代币的60%。这使代理可以直接访问搜索、下载、浏览对等体、监控传输和管理slskd实例——Lidarr中缺失的部分→ 灵魂追寻→ Plex音乐管道。

整个项目——生成器、服务器、测试套件和此README——由AI（Claude）构建，旨在供AI代理安装和使用。

安装

选项1：镍片（推荐）

# 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";
  };
}

无需安装即可快速测试：

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

选项2:uv（非Nix）

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

配置您的MCP客户端

克劳德代码：

# 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_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"
      }
    }
  }
}

环境变量

模块过滤

默认情况下，所有工具都已注册。集 SLSKD_MODULES 只加载您需要的内容：

slskd_get_overview, slskd_search_tools，以及 slskd_report_issue 无论模块选择如何，始终都会注册。

示例配置：

# 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)

所得

TODO:工具计数将在生成器Sprint 1完成后填写。

高级工具（不需要API知识）

安全：确认门

所有突变都需要 confirm=True。没有它，你会得到一个模拟预览：

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

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

列表工具筛选

全部 slskd_list_* 工具支持可选参数：

• fields --要返回的逗号分隔的字段名（例如。 "username,state")
• filter --逗号分隔键=行筛选的值对（例如。 "state=Completed")

错误报告

每个工具的文档字符串都促使人工智能消费者调用 slskd_report_issue 意外错误。

运作原理

蟒蛇 发电机 读取slskd OpenAPI 3.0.1规范（70条路径，93次操作），并通过Jinja2模板生成MCP服务器。当slskd更新其API时，使用 SLSKD_SWAGGER=true，拉取新规范，然后重新运行：

# 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

生成的服务器使用FastMCP和单个 SlskdClient 类（httpx+neneneba API密钥验证通过 X-Api-Key 头球每个API操作一个异步工具函数。

建筑

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

测试

单元测试（无需slskd）

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

集成测试（需要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计划

Sprint 1：发电机核心

• \[\]OpenAPI规范加载器(loader.py)--解析路径、操作、模式
• \[\]命名约定(naming.py) — method+path 到 slskd_{verb}_{resource}
• \[\]模式解析器(schema_parser.py)--提取参数类型，句柄 $ref, allOf
• \[\]上下文生成器(context_builder.py)--分配模块，构建模板上下文
• \[\]代码生成器(codegen.py)--通过Jinja2渲染server.py
• \[\]服务器模板(server.py.j2)--带SlskdClient、模块门控、确认门控的FastMCP服务器
• \[\]生成并验证刀具数量是否符合规格

Sprint 2：质量和正确性

• \[\]应用MCP最佳实践（参见 research/mcp-server-best-practices.md)

- 对大整数（>=2^53）进行消毒 - 从请求参数中排除只读字段 - 参数描述中的枚举值 - 从描述中删除HTML - PATCH默认为无

• \[\]列出工具增强功能： fields, filter 参数
• \[\]高级工具： slskd_get_overview, slskd_search_tools, slskd_report_issue
• \[\]搜索工作流提示→ 下载→ 进口管道
• \[\]使用结构化错误字典包装时出错
• \[\]文件/目录路径参数的Base64编码助手
• \[\]单元测试：命名、模块、列表工具

Sprint 3：集成测试

• \[\]Docker为slskd测试实例编写
• \[\]针对实时slskd的集成测试
• \[\]用于编排的Makefile
• \[\]镍片检查与单元测试

Sprint 4:LLM测试

• \[\]任务配置和自动生成的任务文件
• \[\]在Docker中对slskd运行银行测试
• \[\]测试反馈对文档字符串的改进

Sprint 5：文档和发布

• \[\]在README中填写工具计数
• \[\]连接到nixoconfig .mcp.json
• \[\]PyPI打包+MCP注册表提交

slskd特别注意事项

认证

slskd通过 X-Api-Key 头球该规范没有定义安全方案——身份验证由中间件处理。在slskd设置>常规>API密钥中生成API密钥。

Base64编码路径参数

几个文件/目录端点使用base64编码的路径参数(base64SubdirectoryName, base64FileName).生成器应该添加一个自动编码这些内容的助手。

规范中没有操作ID

slskd规范没有 operationId 字段——工具名称必须完全从HTTP方法+路径派生（与lidarr-mcp的方法相同）。

Swagger是一个功能标志

默认情况下，slskd不公开OpenAPI。要重新生成规范，请使用以下命令运行slskd SLSKD_SWAGGER=true （环境变量）或 --swagger （CLI标志）。

音乐管道的关键工作流程

1. 搜索和下载: slskd_create_search → poll slskd_get_search → 通过浏览结果 slskd_list_search_responses → slskd_create_transfer_download （从特定对等端排队下载）
2. 浏览同行共享: slskd_get_user_browse → slskd_create_user_directory （获取目录列表）
3. 监控下载: slskd_list_transfers_downloads → 检查状态→ slskd_delete_transfers_downloads_completed （透明完成）

依赖项

Nix用户： nix run github:abl030/slskd-mcp --一切捆绑。

非Nix用户： Python 3.11+， 紫外线、fastmcp、httpx、jinja2（由安装者安装） uv sync).

许可证

麻省理工学院