Nqbtc

nqbtc

[](https://deepwiki.com/yjl9903/nqbtc) [](https://www.npmjs.com/package/nqbtc) [](https://lobehub.com/mcp/yjl9903-nqbtc) [](https://github.com/yjl9903/nqbt/actions/workflows/ci.yml)

Run qBittorrent MCP server, and TypeScript qBittorrent WebUI API binding.

Use MCP server CLI

Run qBittorrent MCP server.

Requirements

• Node.js 24 or newer
• qBittorrent and make sure WebUI enabled
• Any MCP client

Getting started

Standard config works in most of the tools (replace the --base-url=... with your real qBittorrent WebUI url).

{
  "mcpServers": {
    "nqbtc": {
      "command": "npx",
      "args": [
        "nqbtc",
        "mcp",
        "--base-url=http://localhost:9091/api/v2"
      ]
    }
  }
}

You can also config username and password of WebUI with --username=xxx and --password=yyy options. Add these options your MCP command args.

npx nqbtc mcp --base-url=http://localhost:9091/api/v2 --username=xxx --password=yyy

It also read local .env file and accept following configurations.

QBITTORRENT_WEBUI_BASE_URL=http://localhost:9091/api/v2
QBITTORRENT_WEBUI_USERNAME=
QBITTORRENT_WEBUI_PASSWORD=

Use Client Library

Installation

npm i nqbt

Usage

import { QBittorrent } from 'nqbt';

const client = new QBittorrent({
  baseURL: 'http://localhost:9091/api/v2',
  username: 'admin',
  password: 'adminadmin'
});

await client.login();

const version = await client.getApplicationVersion();
console.log('qBittorrent version:', version);

const torrents = await client.getTorrentList({
  filter: 'downloading',
  sort: 'dlspeed',
  reverse: true,
  limit: 10
});

console.log('downloading torrents:', torrents.length);

if (torrents[0]) {
  // qBittorrent v5 uses stop/start; v4 uses pause/resume.
  // Both method pairs are kept and auto-switch internally.
  await client.stopTorrents(torrents[0].hash);
  await client.startTorrents(torrents[0].hash);

  // Equivalent aliases:
  // await client.pauseTorrents(torrents[0].hash);
  // await client.resumeTorrents(torrents[0].hash);
}

await client.addNewMagnet('magnet:?xt=urn:btih:', {
  category: 'demo',
  tags: 'sample',
  paused: true
});

await client.logout();

Reference

Official docs:

• WebUI API (qBittorrent 5.0))
• WebUI API (qBittorrent 4.1))

Support TypeScript API:

| Category | TypeScript API | WebUI API | | --- | --- | --- | | Authentication | login | login#login) | | Authentication | logout | logout#logout) | | Application | getApplicationVersion | get-application-version#get-application-version) | | Application | getApiVersion | get-api-version#get-api-version) | | Application | getBuildInfo | get-build-info#get-build-info) | | Application | getApplicationPreferences | get-application-preferences#get-application-preferences) | | Application | setApplicationPreferences | set-application-preferences#set-application-preferences) | | Application | getDefaultSavePath | get-default-save-path#get-default-save-path) | | Application | shutdownApplication | shutdown-application#shutdown-application) | | Application | getCookies | get-cookies#get-cookies) | | Application | setCookies | set-cookies#set-cookies) | | Log | getLog | get-log#get-log) | | Log | getPeerLog | get-peer-log#get-peer-log) | | Sync | getMainData | get-main-data#get-main-data) | | Sync | getTorrentPeersData | get-torrent-peers-data#get-torrent-peers-data) | | Transfer info | getGlobalTransferInfo | get-global-transfer-info#get-global-transfer-info) | | Transfer info | getAlternativeSpeedLimitsState | get-alternative-speed-limits-state#get-alternative-speed-limits-state) | | Transfer info | toggleAlternativeSpeedLimits | toggle-alternative-speed-limits#toggle-alternative-speed-limits) | | Transfer info | getGlobalDownloadLimit | get-global-download-limit#get-global-download-limit) | | Transfer info | setGlobalDownloadLimit | set-global-download-limit#set-global-download-limit) | | Transfer info | getGlobalUploadLimit | get-global-upload-limit#get-global-upload-limit) | | Transfer info | setGlobalUploadLimit | set-global-upload-limit#set-global-upload-limit) | | Transfer info | banPeers | ban-peers#ban-peers) | | Torrent Management | getTorrentList | get-torrent-list#get-torrent-list) | | Torrent Management | getTorrentGenericProperties | get-torrent-generic-properties#get-torrent-generic-properties) | | Torrent Management | getTorrentTrackers | get-torrent-trackers#get-torrent-trackers) | | Torrent Management | getTorrentWebSeeds | get-torrent-web-seeds#get-torrent-web-seeds) | | Torrent Management | getTorrentContents | get-torrent-contents#get-torrent-contents) | | Torrent Management | getTorrentPiecesStates | get-torrent-pieces-states#get-torrent-pieces-states) | | Torrent Management | getTorrentPiecesHashes | get-torrent-pieces-hashes#get-torrent-pieces-hashes) | | Torrent Management | stopTorrents / pauseTorrents | stop-torrents#stop-torrents) | | Torrent Management | startTorrents / resumeTorrents | resume-torrents#resume-torrents) | | Torrent Management | deleteTorrents | delete-torrents#delete-torrents) | | Torrent Management | recheckTorrents | recheck-torrents#recheck-torrents) | | Torrent Management | reannounceTorrents | reannounce-torrents#reannounce-torrents) | | Torrent Management | editTrackers | edit-trackers#edit-trackers) | | Torrent Management | removeTrackers | remove-trackers#remove-trackers) | | Torrent Management | addNewTorrent / addNewMagnet | add-new-torrent#add-new-torrent) | | Torrent Management | addTrackersToTorrent | add-trackers-to-torrent#add-trackers-to-torrent) | | Torrent Management | addPeers | add-peers#add-peers) | | Torrent Management | increaseTorrentPriority | increase-torrent-priority#increase-torrent-priority) | | Torrent Management | decreaseTorrentPriority | decrease-torrent-priority#decrease-torrent-priority) | | Torrent Management | maximalTorrentPriority | maximal-torrent-priority#maximal-torrent-priority) | | Torrent Management | minimalTorrentPriority | minimal-torrent-priority#minimal-torrent-priority) | | Torrent Management | setFilePriority | set-file-priority#set-file-priority) | | Torrent Management | setTorrentShareLimits | set-torrent-share-limits#set-torrent-share-limits) | | Torrent Management | getTorrentDownloadLimit | get-torrent-download-limit#get-torrent-download-limit) | | Torrent Management | setTorrentDownloadLimit | set-torrent-download-limit#set-torrent-download-limit) | | Torrent Management | getTorrentUploadLimit | get-torrent-upload-limit#get-torrent-upload-limit) | | Torrent Management | setTorrentUploadLimit | set-torrent-upload-limit#set-torrent-upload-limit) | | Torrent Management | setTorrentLocation | set-torrent-location#set-torrent-location) | | Torrent Management | setTorrentName | set-torrent-name#set-torrent-name) | | Torrent Management | setTorrentCategory | set-torrent-category#set-torrent-category) | | Torrent Management | setAutomaticTorrentManagement | set-automatic-torrent-management#set-automatic-torrent-management) | | Torrent Management | toggleSequentialDownload | toggle-sequential-download#toggle-sequential-download) | | Torrent Management | setFirstLastPiecePriority | set-firstlast-piece-priority#set-firstlast-piece-priority) | | Torrent Management | setForceStart | set-force-start#set-force-start) | | Torrent Management | setSuperSeeding | set-super-seeding#set-super-seeding) | | Torrent Management | getAllCategories | get-all-categories#get-all-categories) | | Torrent Management | addNewCategory | add-new-category#add-new-category) | | Torrent Management | editCategory | edit-category#edit-category) | | Torrent Management | removeCategories | remove-categories#remove-categories) | | Torrent Management | addTorrentTags | add-torrent-tags#add-torrent-tags) | | Torrent Management | removeTorrentTags | remove-torrent-tags#remove-torrent-tags) | | Torrent Management | getAllTags | get-all-tags#get-all-tags) | | Torrent Management | createTags | create-tags#create-tags) | | Torrent Management | deleteTags | delete-tags#delete-tags) | | Torrent Management | renameFile | rename-file#rename-file) | | Torrent Management | renameFolder | rename-folder#rename-folder) |

> Compatibility note > > - stopTorrents and pauseTorrents are both available; both auto-switch to /torrents/stop (v5) or /torrents/pause (v4). > - startTorrents and resumeTorrents are both available; both auto-switch to /torrents/start (v5) or /torrents/resume (v4).

Related

This package is used to power AnimeSpace, offering a comprehensive solution for automatically following bangumis. It can fetch anime resources, download desired video content, and upload them to the local file system or remote WebDAV server. The downloading process is facilitated by this package.

Credits

• qBittorrent
• @ctrl/qbittorrent

License

MIT License © 2025 XLor

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yjl9903
• Source: yjl9903/nqbtc
• License: MIT

Install and usage instructions live in the source repository linked above.