AI导哈

qBittorrent自动化服务

一个轻量级的JSON-RPC服务，提供qBittorrent的自动化操作，包括查询种子状态和添加新种子等功能。

  • by Jacques-Murray
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Jacques-Murray/mcp-qbit-server

使用说明

MCP qBittorrent服务器

一个轻量级的模型上下文协议（MCP）服务器，通过JSON-RPC公开精心策划的qBittorrent自动化原语。该服务将qBittorrent的WebUI API与严格的验证、依赖性注入工具和Jest-based回归测试相结合，因此代理可以安全地查询torrent状态或添加新的torrent。

亮点

  • JSON-RPC 2.0传输 与单一 /rpc 终点和健康探针 /health.
  • 工具注册表+DI容器 (lib/mcp)在启动时连接qBittorrent感知工具。
  • 严格的论证验证 通过Zod模式来防止格式错误的torrent操作。
  • 可测试的组成根 (createApp)这使得嘲笑成为可能 QBitClient 在Jest测试中。
  • 准备发布Node.js服务 使用基于dotenv的配置和nodemon驱动的开发循环。

建筑

client ──JSON-RPC──> Express (/rpc)
                    │
                    ▼
              JsonRpcHandler
                    │
              ToolService (tools/call)
                    │
              ToolRegistry (DI container)
             ┌──────────────┴──────────────┐
     GetTorrentsTool               AddTorrentTool
             │                             │
             └──────────────QBitClient─────┘
  • lib/qbit/QBitClient 封装了qBittorrent WebUI的身份验证、cookie重用和重试。
  • 工具继承自 McpTool 并宣布自己的Zod inputSchema 加 execute 逻辑。
  • ToolService 验证 tools/call 有效载荷，解析工具 ToolRegistry，运行它，并将成功/错误结果标准化。

需求

  • Node.js 18+（建议使用LTS）
  • npm 10+
  • 在启用WebUI的情况下运行qBittorrent实例

配置

创建一个 .env 启动服务器之前，请先执行以下操作：

PORT=8000
QBIT_BASE_URL=http://localhost:8080
QBIT_USERNAME=admin
QBIT_PASSWORD=secret
QBIT_TIMEOUT=10000

配置选项

  • 端口 （可选）：服务器端口，默认为 8000
  • QBIT_BASE_URL （必填）：qBittorrent WebUI URL（必须以http://或https://开头）
  • QBIT_用户名 （必填）：qBittorrent用户名
  • QBIT_PASSWORD （必填）：qBittorrent密码
  • QBIT超时 （可选）：请求超时（毫秒），默认为 10000 （10秒）

安装和本地运行

npm install
npm run dev
  • npm run dev 使用nodemon启动服务，因此代码编辑会触发重新加载。
  • 使用 npm start 在生产环境中运行 server.js 直接。

健康和RPC端点

方法 路径 描述
得到 /health 退货 { status: "ok" } 用于准备就绪探测。
职位 /rpc 接受用于MCP工具的JSON-RPC 2.0有效载荷。

样品申请

curl -X POST http://localhost:8000/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "qbit/getTorrents",
      "arguments": { "filter": "all" }
    }
  }'

样品响应

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": false,
    "content": [
      { "name": "ubuntu.iso", "state": "seeding", "progress": 1 },
      { "name": "movie.mkv", "state": "downloading", "progress": 0.42 }
    ]
  }
}

可用工具

工具名称 描述 参数
qbit/getTorrents 列出种子并返回简化视图(name, hash, size, progress, state, eta).过滤器状态值（例如。， all, downloading, seeding)通过 filter 争论。 filter?: string
qbit/addTorrent 使用磁铁添加新的torrent或 .torrent URL，返回成功标志。 url: string (valid URL)

每个工具在接触qBittorrent之前都会强制执行自己的Zod模式，因此格式错误的有效载荷永远不会到达客户端。

测试

运行Jest套件（模拟qBittorrent，因此不需要外部依赖）：

npm test

现场测试 tests/mcp.test.js 涵盖健康检查、传输错误以及两种刀具路径。

部署说明

  • 该服务是无状态的；在任何反向代理后面运行并水平缩放。
  • 请确保可以从此服务器访问qBittorrent WebUI API，并且凭据的作用域正确。
  • 考虑设置 NODE_ENV=production 因此Express省略了堆栈跟踪。
  • 安全：参见 安全.md 安全最佳实践，包括：
    • 使用TLS/SSL在反向代理后面运行
    • 实施速率限制
    • 使用强凭据
    • 网络隔离建议

贡献

生活指南 CONTRIBUTING.md简而言之：打开一个问题，运行 npm test 在提交之前，记录新工具。

行为准则

参与受以下规定的约束 CODE_OF_CONDUCT.md，它改编了《贡献者公约》，以保持社区的欢迎。

许可证

根据MIT许可证分发。看 LICENSE 了解详情。

维护者

由创建和维护 雅克·默里 (jacquesmmurray@gmail.com).

相关 MCP