qBittorrent MCP Server

一个用于 qBittorrent 集成的 Model Context Protocol (MCP) 服务器。允许通过 MCP 协议管理 qBittorrent 下载任务。

功能

• ➕ 添加种子: 支持磁力链接、URL 或上传 .torrent 文件
• 📋 获取种子列表: 查看所有下载任务
• ⏸️ 暂停/恢复: 控制下载任务
• 🗑️ 删除任务: 删除种子（可选删除文件）
• 📂 分类管理: 查看和管理分类
• 📊 传输信息: 获取全局下载/上传统计

安装

前置要求

• Node.js >= 18.0.0
• qBittorrent 已安装并运行
• qBittorrent Web UI 已启用

安装步骤

# 克隆或下载此项目
cd qBittorrentMcp

# 安装依赖
npm install

# 添加可执行权限
chmod +x src/index.js

配置

环境变量

| 变量名 | 必需 | 默认值 | 说明 | |--------|------|--------|------| | QBITTORRENT_BASE_URL | 否 | http://localhost:8080 | qBittorrent Web UI 地址 | | QBITTORRENT_USERNAME | 否 | admin | 登录用户名 | | QBITTORRENT_PASSWORD | 是 | - | 登录密码 |

获取密码

1. 打开 qBittorrent Web UI
2. 使用你的用户名和密码登录
3. 将这些凭据设置为环境变量

使用方法

推荐方式：全局安装 (⭐ 推荐)

# 全局安装（推荐）
npm install -g /path/to/qBittorrentMcp

然后在 Claude Desktop 中配置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "qbittorrent": {
      "command": "qbittorrent-mcp-server",
      "env": {
        "QBITTORRENT_BASE_URL": "http://localhost:8080",
        "QBITTORRENT_USERNAME": "admin",
        "QBITTORRENT_PASSWORD": "your-password"
      }
    }
  }
}

方式 1: 本地安装后运行

# 安装依赖
cd /path/to/qBittorrentMcp
npm install

# 启动服务器
npm start

在 Claude Desktop 中配置：

{
  "mcpServers": {
    "qbittorrent": {
      "command": "node",
      "args": ["/path/to/qBittorrentMcp/src/index.js"],
      "env": {
        "QBITTORRENT_BASE_URL": "http://localhost:8080",
        "QBITTORRENT_USERNAME": "admin",
        "QBITTORRENT_PASSWORD": "your-password"
      }
    }
  }
}

方式 2: 使用 npx (无需安装)

# 直接运行（自动下载并运行）
npx qbittorrent-mcp-server

在 Claude Desktop 中配置：

{
  "mcpServers": {
    "qbittorrent": {
      "command": "npx",
      "args": ["qbittorrent-mcp-server"],
      "env": {
        "QBITTORRENT_BASE_URL": "http://localhost:8080",
        "QBITTORRENT_USERNAME": "admin",
        "QBITTORRENT_PASSWORD": "your-password"
      }
    }
  }
}

注意: npx 方式首次运行时会自动下载包，需要网络连接。

环境变量配置

无论使用哪种方式，都需要设置以下环境变量：

# Linux/macOS
export QBITTORRENT_BASE_URL="http://localhost:8080"
export QBITTORRENT_USERNAME="admin"
export QBITTORRENT_PASSWORD="your-password"

# Windows (PowerShell)
$env:QBITTORRENT_BASE_URL="http://localhost:8080"
$env:QBITTORRENT_USERNAME="admin"
$env:QBITTORRENT_PASSWORD="your-password"

# Windows (CMD)
set QBITTORRENT_BASE_URL=http://localhost:8080
set QBITTORRENT_USERNAME=admin
set QBITTORRENT_PASSWORD=your-password

可用工具

1. qbittorrent_get_torrents

获取种子列表。

参数:

• filter (string, 可选): 状态筛选
  • all: 所有
  • downloading: 下载中
  • seeding: 做种中
  • completed: 已完成
  • paused: 已暂停
  • active: 活跃
  • inactive: 不活跃
  • stalled: 停滞
  • error: 错误
• category (string, 可选): 按分类筛选
• sort (string, 可选): 排序字段 (hash, name, size, progress, download_speed, upload_speed, etc.)
• reverse (boolean, 可选): 反向排序
• limit (number, 可选): 限制结果数量
• offset (number, 可选): 分页偏移

响应:

{
  "success": true,
  "count": 20,
  "torrents": [
    {
      "hash": "...",
      "name": "种子名称",
      "size": 8589934592,
      "progress": 0.75,
      "downloadSpeed": 1048576,
      "uploadSpeed": 524288,
      "eta": 3600,
      "state": "downloading",
      "category": "movies",
      "savePath": "/downloads"
    }
  ]
}

2. qbittorrent_get_torrent_info

获取单个种子的详细信息。

参数:

• hash (string, 必需): 种子哈希值

3. qbittorrent_add_torrent

添加新种子。支持三种方式：

方式 1: 磁力链接

{
  "url": "magnet:?xt=urn:btih:...",
  "savepath": "/downloads",
  "category": "movies",
  "paused": false
}

方式 2: HTTP/HTTPS 链接

{
  "url": "https://example.com/file.torrent",
  "savepath": "/downloads"
}

方式 3: 上传 .torrent 文件

{
  "torrentBuffer": "base64编码的torrent文件内容",
  "savepath": "/downloads",
  "category": "movies",
  "paused": false
}

完整参数:

• url (string): 种子 URL 或磁力链接
• torrentBuffer (string): Base64 编码的 .torrent 文件内容
• savepath (string, 可选): 保存路径
• category (string, 可选): 分类
• paused (boolean, 可选): 是否暂停，默认 false
• skip_checking (boolean, 可选): 跳过哈希检查，默认 false
• root_folder (boolean, 可选): 创建根文件夹，默认 true

4. qbittorrent_pause_torrent

暂停种子下载。

参数:

• hashes (string | array, 必需): 单个哈希、哈希数组或 "all"

// 暂停单个
{ "hashes": "abc123..." }

// 暂停多个
{ "hashes": ["abc123...", "def456..."] }

// 暂停所有
{ "hashes": "all" }

5. qbittorrent_resume_torrent

恢复种子下载。参数同 qbittorrent_pause_torrent。

6. qbittorrent_delete_torrent

删除种子。

参数:

• hashes (string | array, 必需): 单个哈希、哈希数组或 "all"
• deleteFiles (boolean, 可选): 是否同时删除文件，默认 false

{
  "hashes": "abc123...",
  "deleteFiles": false
}

7. qbittorrent_get_categories

获取所有分类。

8. qbittorrent_get_transfer_info

获取全局传输信息。

响应:

{
  "success": true,
  "transferInfo": {
    "downloadSpeed": 10485760,
    "uploadSpeed": 5242880,
    "downloaded": 107374182400,
    "uploaded": 53687091200,
    "connectionCount": 150,
    "freeSpaceOnDisk": 1099511627776
  }
}

开发

项目结构

qBittorrentMcp/
├── src/
│   └── index.js          # MCP 服务器实现
├── tests/
│   ├── test-server.test.js    # MCP 服务器测试
│   └── test-api.test.js       # API 集成测试
├── package.json
└── README.md

运行测试

# 测试 MCP 服务器
npm run test:server

# 测试 API 集成
npm run test:api

# 运行所有测试
npm run test:all

开发模式

# 使用 --watch 模式
npm run dev

示例用法

添加种子下载

# 在 Claude 中询问（如果配合 Jackett MCP）
"搜索 'Interstellar 2014' 并添加第一个结果到下载队列"

Claude 会：

1. 使用 Jackett MCP 搜索
2. 从搜索结果中选择一个
3. 使用 qBittorrent MCP 添加下载

查看下载进度

# 在 Claude 中询问
"查看当前所有下载任务"
"显示正在下载的电影"

管理下载任务

# 暂停下载
"暂停所有电影下载"

# 恢复下载
"恢复刚才暂停的下载"

# 删除已完成
"删除所有已完成的任务，但保留文件"

查看统计信息

# 在 Claude 中询问
"当前下载速度是多少？"
"总共下载了多少数据？"
"还剩多少磁盘空间？"

高级功能

上传 .torrent 文件

当索引器只提供 .torrent 文件链接时（没有磁力链），MCP 客户端可以：

1. 下载 .torrent 文件
2. 转换为 base64 编码
3. 使用 torrentBuffer 参数上传

示例代码（客户端）：

// 下载 .torrent 文件
const response = await fetch(torrentUrl);
const buffer = await response.arrayBuffer();
const base64 = Buffer.from(buffer).toString('base64');

// 上传到 qBittorrent
await client.callTool({
  name: "qbittorrent_add_torrent",
  arguments: {
    torrentBuffer: base64,
    savepath: "/downloads"
  }
});

分类管理

# 在 Claude 中询问
"创建一个 'TV Shows' 分类"
"将所有电视剧移到 TV Shows 分类"
"显示所有分类及其种子数"

批量操作

# 批量暂停
"暂停所有下载速度低于 1MB/s 的任务"

# 批量删除
"删除所有做种比例大于 5.0 的任务"

与 Jackett MCP 配合使用

当同时配置 Jackett MCP 和 qBittorrent MCP 时，你可以：

# 完整工作流
"搜索 'Dune Part Two 2024'，选择 4K 版本，下载到 /movies/4k 分类"

常见问题

Q: 上传 .torrent 文件失败？

A: 检查以下几点：

1. 文件大小是否合理（通常几 KB 到几 MB）
2. base64 编码是否正确
3. qBittorrent 磁盘空间是否足够

Q: 种子添加后不下载？

A: 可能的原因：

1. 没有可用的 peers/seeds
2. 网络连接问题
3. Tracker 无响应
4. 种子已死（没有人在做种）

使用 qbittorrent_get_torrent_info 查看详细信息。

Q: Session 过期怎么办？

A: MCP 服务会自动处理 session 过期并重新登录，无需手动干预。

Q: 如何设置下载路径？

A: 添加种子时使用 savepath 参数：

{
  "url": "magnet:?...",
  "savepath": "/path/to/downloads"
}

相关资源

• qBittorrent 官网
• qBittorrent Web API 文档
• Model Context Protocol

许可证

MIT

作者

MCP Community

更新日志

v1.0.0 (2025-01-XX)

• 初始版本
• 支持添加种子（磁力链、URL、文件上传）
• 支持暂停/恢复/删除操作
• 支持查询种子列表和详细信息
• 支持 Session 自动管理
• 支持 GET 请求查询参数
• 完整的错误处理