关键词

qBittorrent下载电影管理LLM工具集成家庭影院助手

项目简介

'turtle_app' 仓库是一个AI驱动的家庭影院助手，其核心之一是 qBittorrent MCP 服务器。该服务器作为中间件，将流行的BT下载客户端qBittorrent的Web API功能封装成符合 Model Context Protocol (MCP) 标准的工具。这使得大型语言模型（LLM）客户端（例如 'turtle_app' 中的下载管理器代理）能够以标准化、可扩展的方式与qBittorrent进行交互，从而实现电影下载、状态查询、文件管理等功能，而无需LLM直接了解qBittorrent的底层API细节。

主要功能点

  • 托管qBittorrent功能为MCP工具: 将qBittorrent的各种API（如列出下载、搜索资源、添加下载、暂停/恢复/删除下载、获取详情、获取配置）封装为标准化的MCP工具（例如 'qb_list_torrents', 'qb_search_torrents' 等）。
  • 标准化数据交互: 使用Pydantic模型清晰定义了每个MCP工具的输入参数和输出结果，确保了数据格式的统一性和可预测性，便于LLM客户端理解和使用。
  • HTTP传输协议支持: MCP服务器通过HTTP协议与客户端通信，提供了广泛的兼容性。
  • 安全认证: 支持与qBittorrent Web API的用户名/密码认证，确保对下载客户端操作的安全性。

安装步骤

此qBittorrent MCP服务器通常作为 'turtle_app' 整体部署的一部分，通过Docker Compose进行部署，从而简化了依赖管理。

  1. 克隆仓库:

    git clone https://github.com/elisarchod/turtle_app.git
cd turtle_app

  2. 配置环境变量: 复制 '.env.example' 文件到项目根目录并重命名为 '.env'。编辑 '.env' 文件，务必配置以下用于MCP服务器连接实际qBittorrent实例的凭证：

    • 'TURTLEAPP_QB_QBITTORRENT_URL': qBittorrent Web API的实际URL（例如 'http://qbittorrent:8080' 如果在Docker Compose内部，或 'http://localhost:8080' 如果本地运行）。
    • 'TURTLEAPP_QB_QBITTORRENT_USERNAME': qBittorrent Web UI的用户名。
    • 'TURTLEAPP_QB_QBITTORRENT_PASSWORD': qBittorrent Web UI的密码。

    '.env' 示例 (仅MCP相关部分):

    # ... 其他API Keys ...

# qBittorrent MCP Server connects to THIS qBittorrent instance
TURTLEAPP_QB_QBITTORRENT_URL=http://qbittorrent:8080
TURTLEAPP_QB_QBITTORRENT_USERNAME=admin
TURTLEAPP_QB_QBITTORRENT_PASSWORD=adminadmin

# ... 其他设置 ...

  3. 使用Docker Compose启动 (推荐): 进入 'build' 目录并运行 Docker Compose 命令。这将启动所有必要的服务，包括 'turtle_app' 主应用、qBittorrent MCP服务器和实际的qBittorrent实例。

    cd build
docker-compose up -d

    注意: 此时，qBittorrent MCP服务器将监听在 'http://localhost:8001/mcp' (这是Docker Compose对外暴露的端口)。qBittorrent Web UI将监听在 'http://localhost:15080'。

服务器配置

MCP客户端（如 'turtle_app' 主应用）连接到此qBittorrent MCP服务器所需的JSON格式配置信息如下。此配置通常由客户端应用程序维护，并用于初始化其MCP连接。

{
  "server_name": "qbittorrent",
  "command": "python",
  "args": [
    "mcp-servers/qbittorrent-mcp/src/mcp_qbittorrent/server.py",
    "--host", "0.0.0.0",
    "--port", "8000"
  ],
  "endpoint": "http://localhost:8001/mcp",
  "description": "一个提供qBittorrent下载管理功能的MCP服务器。",
  "transport": "streamable_http"
}

配置参数注释:

  • 'server_name': MCP服务器的唯一标识名称，客户端通过此名称引用和发现服务器。
  • 'command': 启动MCP服务器进程的命令行程序，通常是 'python' 或其他脚本解释器。
  • 'args': 传递给 'command' 的参数列表，用于指定服务器脚本路径、监听地址和端口等。这里的 '0.0.0.0' 表示监听所有网络接口，'8000' 是容器内部的监听端口。
  • 'endpoint': MCP客户端实际连接到MCP服务器的URL。在Docker Compose部署中，这通常是宿主机映射到容器的公开端口（例如 'http://localhost:8001/mcp'）。
  • 'description': MCP服务器的简短功能描述，有助于客户端了解其提供的能力。
  • 'transport': 客户端与服务器通信使用的传输协议，'streamable_http' 表示基于HTTP的流式传输。

基本使用方法

此qBittorrent MCP服务器本身不提供直接的用户界面，其设计目的是作为后端服务，供LLM客户端调用。LLM客户端会通过JSON-RPC协议发送请求到其 '/mcp' 端点，调用其暴露的MCP工具。

例如，'turtle_app' 中的下载管理器代理会通过调用 'qb_search_torrents' 工具来搜索用户指定的电影，并通过 'qb_list_torrents' 工具来获取当前下载的状态和进度。用户通过 'turtle_app' 的 '/chat' 接口与AI助手交互，AI助手（作为一个MCP客户端）会根据用户需求间接利用此MCP服务器提供的强大功能。

信息

分类

生产力应用

访问项目