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 文件以获取详细信息。