p2p-tools-mcp

One npm package with a unified CLI and two local-first MCP servers for VPN checks, Jackett search, and qBittorrent lifecycle operations:

• p2p-tools provides the same operations as a JSON-first command-line interface.
• vpn-mcp controls and inspects a supported NordVPN CLI.
• torrent-mcp exposes explicit jackett_* and qbittorrent_* tools.

All three entrypoints share one configuration loader, validated operation layer, network guard, normalized responses, credential/path redaction, and fixed public errors. The MCP servers use stdio and keep VPN lifecycle separate from torrent lifecycle.

Platform support

The Node.js servers and Jackett/qBittorrent integrations run on Windows, macOS, and Linux.

The bundled NordVPN adapter has narrower support:

Capability	Linux	Windows	macOS
Connect/disconnect	Supported CLI	Supported command switches	Not supported by this adapter
Status and vpn_require_active	Supported CLI	Not supported by this adapter	Not supported by this adapter
Built-in torrent network guard	Supported	Use an external boundary	Use an external boundary

For an operating-system-neutral deployment, run Jackett and qBittorrent behind a dedicated VPN container/network boundary and disable the host-level guard. See Torrent-side VPN isolation.

Requirements

• Node.js 20 or newer. CI currently tests Node.js 24 on Windows, macOS, and Linux.
• Jackett for search and indexer operations.
• qBittorrent with its Web UI enabled for torrent operations.
• A supported NordVPN CLI only when using vpn-mcp or the built-in network guard.

Quick start

From a reviewed source checkout:

npm ci
npm test
npm run build

The build produces all three package commands. Try the CLI directly from the checkout:

node dist/p2p-tools.js --help
node dist/p2p-tools.js jackett category --query "audio flac"

Copy the annotated configuration to an untracked location, add the service credentials, and register one or both servers with an MCP client:

mcp_servers:
  torrent:
    command: node
    args: ["<repo-root>/dist/torrent-mcp.js"]
    env:
      P2P_TOOLS_CONFIG: "<private-config-file>"

Add vpn-mcp only when the host supports the required VPN operation:

mcp_servers:
  vpn:
    command: node
    args: ["<repo-root>/dist/vpn-mcp.js"]
    env:
      P2P_TOOLS_CONFIG: "<private-config-file>"

Restart the MCP client after changing its registration. A server started directly in a terminal normally appears idle because it is waiting for MCP messages on stdin.

Configuration

Set P2P_TOOLS_CONFIG to a YAML file. When it is unset, the servers use loopback defaults for Jackett and qBittorrent, but authenticated operations will still require their credentials.

vpn:
  provider: nordvpn
  command: nordvpn

network_guard:
  enabled: true
  requireVpnConnected: true
  guarded_operations:
    - torrent_search
    - torrent_caps
    - torrent_list_indexers
    - torrent_add

jackett:
  baseUrl: http://127.0.0.1:9117
  apiKey: <jackett-api-key>

qbittorrent:
  baseUrl: http://127.0.0.1:8080
  username: <web-ui-username>
  password: <web-ui-password>

The guard configuration deliberately uses stable internal operation IDs (torrent_search, torrent_add, and so on), including when callers use the newer canonical tool names. See the User Guide for the full mapping and environment-variable overrides.

On Windows, set vpn.command to the trusted absolute path of the NordVPN command executable. The adapter deliberately does not inherit the caller's search path.

File-permission hardening is optional. If the host is shared or its default file permissions are broad, restrict the populated configuration to the account that launches p2p-tools or either MCP server.

CLI

The same package installs p2p-tools alongside vpn-mcp and torrent-mcp:

p2p-tools vpn status
p2p-tools jackett search --query "example query" --limit 25
p2p-tools qbit list --filter downloading

The CLI writes the same { "ok": true, "data": ... } and { "ok": false, "error": ... } envelopes as the MCP tools. It exits with 0 for success, 1 for an operation failure, and 2 for invalid invocation or configuration. Use --stdin to supply a JSON object and --compact for one-line output.

See the CLI Guide for every command, option, stdin examples, and delete confirmation behavior.

Canonical tools

vpn-mcp:

• vpn_status
• vpn_connect
• vpn_disconnect
• vpn_public_ip
• vpn_require_active

torrent-mcp, Jackett:

• jackett_test_connection
• jackett_search
• jackett_caps
• jackett_list_indexers
• jackett_get_category

torrent-mcp, qBittorrent:

• qbittorrent_test_connection
• qbittorrent_add_magnet
• qbittorrent_add_torrent_url
• qbittorrent_list_torrents
• qbittorrent_get_torrent
• qbittorrent_pause_torrent
• qbittorrent_resume_torrent
• qbittorrent_delete_torrent

The torrent_* names are deprecated compatibility aliases for the 0.2 release line. New integrations should use the canonical names above.

Safety and privacy behavior

• Successful service responses pass through a recursive credential/path redactor.
• Unexpected exceptions become stable public errors instead of exposing raw messages.
• Jackett results omit comments, arbitrary attributes, unsafe download URLs, and peer-identifying fields; safe magnet output contains only the BTIH identifier.
• qBittorrent output omits local save paths and other unnecessary raw API fields.
• VPN child processes receive a small sanitized environment.
• vpn_public_ip contacts an external IP-check service and returns the current public IP.
• qbittorrent_delete_torrent keeps downloaded files unless delete_files: true is supplied.
• The network guard is fail-closed for configured operations, but it does not connect the VPN automatically.

Documentation

• User Guide: setup, configuration, tool arguments, verification, privacy, and troubleshooting.
• CLI Guide: CLI installation, commands, options, JSON input, output, and exit codes.
• Hermes wiring: focused MCP registration examples.
• Standalone migration: migrate from separate Jackett/qBittorrent servers.
• Torrent-side VPN isolation: containerized network-boundary deployment.
• Versioning: compatibility and release policy.
• Example config: annotated configuration template.

Development

npm test          # Vitest suite
npm run check     # TypeScript validation without output
npm run build     # compile into dist/

Generated binaries:

• dist/p2p-tools.js
• dist/vpn-mcp.js
• dist/torrent-mcp.js

License

Released under the Viral Public License. The VPL applies its full terms to redistribution and to works that copy, depend on, link to, derive from, or combine with this work.