Nicotine+ Soulseek MCP 服务器

一个无状态、仅本地的模型上下文协议（MCP）服务器，直接与 Nicotine+（Soulseek）网络引擎交互。

它允许 AI 助手（如 Claude Desktop、Antigravity 或其他 MCP 客户端）搜索 Soulseek 点对点网络、评估音频质量/比特率、选择队列最短且速度最快的下载候选、自动批量下载曲目列表，并监控传输进度。

功能特性

• 本地且无状态：使用官方 Python MCP SDK 在本地通过标准 STDIO 运行。

• 自动检测桌面版 Nicotine+ 配置：自动读取您现有的桌面版 Nicotine+ 配置（~/.config/nicotine/config 或 %APPDATA%/nicotine/config），无需手动重新输入即可继承您现有的 Soulseek 账号和下载目录。

• 智能排序与评分：基于以下条件评估并对搜索结果进行排序：

  • 音频质量（320 kbps MP3、FLAC、V0 等）

  • 队列长度（优先选择具有免费上传槽位 / 队列为 0 的对等节点）

  • 对等节点上传速度（以 KB/s 为单位）

• 批量自动化（auto_find_and_download）：将歌曲或专辑列表粘贴给您的 AI 助手；它将自动搜索、为每项选择最优文件并加入下载队列。

• 实时传输监控（get_downloads_status）：跟踪下载进度百分比、下载速度和队列位置。

• 高质量代码：使用 uv 构建，采用严格的类型注解、Pydantic v2 模式，并通过 ruff 和 pytest 验证。

可用的 MCP 工具

🚀 面向 AI 助手的 1 分钟零安装设置

您可以将任何 AI 助手（Claude Desktop、Antigravity、Cursor、Windsurf、Cline、Roo Code 等）直接指向此 GitHub 仓库，无需克隆或手动管理虚拟环境。

推荐方式：通过 uvx 零安装（macOS、Windows、Linux）

在您的 MCP 设置文件中添加以下内容（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "nicotine-plus": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ccombe/nicotine-plus-mcp@v0.2.0",
        "nicotine-mcp"
      ]
    }
  }
}

[!TIP]

• uvx 会自动下载、在隔离缓存中安装并按需启动服务器。

• 您可以通过添加 @v0.2.0 来固定特定版本（推荐以确保稳定性），或使用默认的 master 分支以始终获取最新更新。

💻 本地 Git 克隆设置

如果您更倾向于克隆并在本地运行服务器：

git clone https://github.com/ccombe/nicotine-plus-mcp.git
cd nicotine-plus-mcp
uv run nicotine-mcp

本地 MCP 配置

macOS / Linux

{
  "mcpServers": {
    "nicotine-plus": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/nicotine-plus-mcp",
        "run",
        "nicotine-mcp"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "nicotine-plus": {
      "command": "uv.exe",
      "args": [
        "--directory",
        "C:\\path\\to\\nicotine-plus-mcp",
        "run",
        "nicotine-mcp"
      ]
    }
  }
}

[!NOTE] 跨平台自动检测：

• Linux：自动使用 ~/.config/nicotine/config 和 $XDG_DATA_HOME/nicotine。

• macOS：自动检查 ~/Library/Application Support/nicotine 和 ~/.config/nicotine。

• Windows：自动使用 %APPDATA%\nicotine\config。

如果您已经在电脑上使用 Nicotine+ 桌面应用，则无需任何设置或凭据。如果您想指定自定义凭据或路径，只需在 env 块中添加 SOULSEEK_USERNAME、SOULSEEK_PASSWORD 和 SOULSEEK_DOWNLOAD_DIR。

与您的 AI 助手一起使用的示例

您可以粘贴如下提示请求：

"请搜索并下载以下曲目，要求 320kbps MP3 格式，选择具有免费上传槽位的最快对等节点：

1. Daft Punk - Around the World

2. Aphex Twin - Xtal

3. Boards of Canada - Dayvan Cowboy"

助手将使用该列表执行 auto_find_and_download，您可以随时通过询问 "我的下载进行得怎么样了？"（该操作会调用 get_downloads_status）来查看进度。

开发、测试与验证

运行所有测试套件：

uv run pytest

运行代码检查器与格式检查器（ruff）：

uv run ruff check src/nicotine_mcp tests
uv run ruff format --check src/nicotine_mcp tests

使用 ty 运行严格类型检查：

uv run ty check src/nicotine_mcp tests

审计依赖项的安全漏洞与锁文件完整性：

uv run pip-audit
uv lock --check