Nicotine+ Soulseek MCP Server

ステートレスでローカルのみで動作する、Nicotine+ (Soulseek) ネットワークエンジンに直接接続する Model Context Protocol (MCP) サーバーです。

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/秒）

• 一括自動化（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