Rqbit MCP

🚀 rqbit的Python API包裝器與MCP服務器

本倉庫提供了一個適用於 rqbit 種子客戶端的Python API包裝器和一個MCP（模型上下文協議）服務器，方便將其集成到其他應用程序或服務中。

🚀 快速開始

本項目為你提供了便捷的方式來使用 rqbit 種子客戶端，下面將詳細介紹項目的特性、安裝步驟和使用方法。

✨ 主要特性

• 為 rqbit 種子客戶端提供API包裝器。
• 提供MCP服務器接口，支持標準化通信（標準輸入輸出、服務器發送事件、可流式傳輸的HTTP）。
• 提供以下工具：
  • list_torrents：列出所有種子及其詳細信息。
  • download_torrent：從磁力鏈接或文件下載種子。
  • get_torrent_details：獲取特定種子的詳細信息。
  • get_torrent_stats：獲取特定種子的統計信息/狀態。
  • pause_torrent：暫停種子下載。
  • start_torrent：開始種子下載。
  • forget_torrent：遺忘種子，但保留文件。
  • delete_torrent：刪除種子及其文件。

📦 安裝指南

前提條件

• 運行中的 rqbit 實例（包含在Docker Compose中）。
• Python 3.10+（使用PyPI安裝時需要）。
• uv（用於本地開發）

配置

本應用程序需要 rqbit 實例的URL。

設置環境變量：將項目根目錄下的 .env.example 複製為 .env，並根據你的設置進行編輯。應用程序將自動從 .env 加載變量：

• MCP服務器：
  • RQBIT_URL：rqbit實例的URL（默認：http://localhost:3030）。
  • RQBIT_HTTP_BASIC_AUTH_USERPASS：如果rqbit實例中設置了基本認證。
• rqbit實例：
  • RQBIT_HTTP_BASIC_AUTH_USERPASS：基本認證的用戶名和密碼，格式為 username:password。
  • RQBIT_HTTP_API_LISTEN_ADDR：HTTP API的監聽地址（例如：0.0.0.0:3030）。
  • RQBIT_UPNP_SERVER_ENABLE：啟用或禁用UPnP服務器（例如：true 或 false）。
  • RQBIT_UPNP_SERVER_FRIENDLY_NAME：UPnP服務器的友好名稱（例如：rqbit-media）。
  • RQBIT_EXPERIMENTAL_UTP_LISTEN_ENABLE：啟用或禁用uTP監聽器（默認：false）。
  • 更多變量和信息請查看 rqbit。

安裝方式

你可以選擇以下其中一種安裝方法：

從PyPI安裝（推薦）

這種方法適合將該包作為庫使用或在不修改代碼的情況下運行服務器。

1. 從PyPI安裝包：

pip install rqbit-mcp

2. 在運行應用程序的目錄中創建一個 .env 文件，並添加你的 rqbit URL：

RQBIT_URL=http://localhost:3030

3. 運行MCP服務器（默認：標準輸入輸出）：

python -m rqbit_client

本地開發安裝

這種方法適用於想要修改源代碼的貢獻者，需要使用 uv：

1. 克隆倉庫：

git clone https://github.com/philogicae/rqbit-mcp.git
cd rqbit-mcp

2. 使用 uv 安裝依賴：

uv sync --locked

3. 通過複製示例文件創建配置文件，並添加你的設置：

cp .env.example .env

4. 運行MCP服務器（默認：標準輸入輸出）：

uv run -m rqbit_client

Docker安裝

這種方法使用Docker在容器中運行服務器，compose.yaml 包含 rqbit 種子客戶端。

1. 克隆倉庫（如果你還沒有克隆）：

git clone https://github.com/philogicae/rqbit-mcp.git
cd rqbit-mcp

2. 通過複製示例文件創建配置文件，並添加你的設置：

cp .env.example .env

3. 使用Docker Compose構建並運行容器（默認端口：8000）：

docker compose up --build -d

4. 查看容器日誌：

docker logs rqbit-mcp -f

💻 使用示例

作為Python API包裝器

import asyncio
from rqbit_client.wrapper import RqbitClient

async def main():
    # 從.env文件中讀取RQBIT_URL，若未找到則使用默認值 (http://localhost:3030)
    async with RqbitClient() as client:
        # 下載種子
        magnet_link = "magnet:?xt=urn:btih:..."
        torrent = await client.download_torrent(magnet_link)
        print(torrent)

        # 檢查狀態
        status = await client.get_torrent_stats(torrent["id"])
        print(status)

        # 列出種子
        torrents = await client.list_torrents()
        print(torrents)

if __name__ == "__main__":
    asyncio.run(main())

作為MCP服務器

from rqbit_client import RqbitMCP

RqbitMCP.run(transport="sse") # 可選擇 'stdio', 'sse', 或 'streamable-http'

通過MCP客戶端使用

可與任何兼容MCP的客戶端一起使用，可用工具如下：

• list_torrents：列出所有種子。
• download_torrent：通過磁力鏈接或文件路徑下載種子。
• get_torrent_details：獲取特定種子的詳細信息。
• get_torrent_stats：獲取特定種子的統計信息/狀態。
• pause_torrent：暫停種子下載。
• start_torrent：開始種子下載。
• forget_torrent：遺忘種子，但保留文件。
• delete_torrent：刪除種子及其文件。

以Windsurf為例

配置如下：

{
  "mcpServers": {
    ...
    # 使用標準輸入輸出（僅需uv）
    "rqbit-mcp": {
      "command": "uvx",
      "args": [ "rqbit-mcp" ],
      "env": { 
        "RQBIT_URL": "http://localhost:3030", # （可選）默認rqbit實例URL
        "RQBIT_HTTP_BASIC_AUTH_USERPASS": "username:password" # （可選）僅在rqbit實例中設置時使用
      }
    },
    # 使用sse傳輸（需要安裝）
    "rqbit-mcp": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    },
    # 使用可流式傳輸的HTTP傳輸（需要安裝）
    "rqbit-mcp": {
      "serverUrl": "http://127.0.0.1:8000/mcp" 
    },
    ...
  }
}

📚 詳細文檔

變更日誌

有關本項目的變更歷史，請查看 CHANGELOG.md。

貢獻指南

歡迎貢獻代碼！請提交問題或拉取請求。

📄 許可證

本項目採用MIT許可證，請查看 LICENSE 文件以獲取詳細信息。