qBittorrent MCP Server

Instructions

Implementation Reference

• main.py:96-152 (handler)

  The handler function decorated with @mcp.tool() that implements the download_torrent tool logic using the qBittorrent API to add torrents by URL or magnet link.

  @mcp.tool()
  def download_torrent(
      url: str,
      save_path: str = None,
      category: str = None,
      tags: str = None,
      paused: bool = False
  ) -> dict[str, Any]:
      """
      Download a torrent by URL or magnet link.
  
      Args:
          url: Torrent URL or magnet link
          save_path: Directory to save the torrent (optional)
          category: Category to assign to the torrent (optional)
          tags: Comma-separated tags to assign (optional)
          paused: Start torrent in paused state (default: False)
  
      Returns:
          Status information about the download
      """
      client = get_qbt_client()
  
      # Prepare options
      options = {}
      if save_path:
          options["savepath"] = save_path
      if category:
          options["category"] = category
      if tags:
          options["tags"] = tags
      if paused:
          options["paused"] = "true"
  
      # Add torrent
      try:
          result = client.torrents_add(urls=url, **options)
  
          if result == "Ok.":
              return {
                  "status": "success",
                  "message": "Torrent added successfully",
                  "url": url
              }
          else:
              return {
                  "status": "error",
                  "message": f"Failed to add torrent: {result}",
                  "url": url
              }
      except Exception as e:
          return {
              "status": "error",
              "message": f"Error adding torrent: {str(e)}",
              "url": url
          }

• main.py:17-38 (helper)

  Helper function to initialize and return the qBittorrent client instance used by the download_torrent handler.

  def get_qbt_client():
      """Get or create qBittorrent client instance."""
      global qbt_client
  
      if qbt_client is None:
          host = os.getenv("QBITTORRENT_HOST", "http://localhost:8080")
          username = os.getenv("QBITTORRENT_USERNAME", "admin")
          password = os.getenv("QBITTORRENT_PASSWORD", "adminadmin")
  
          qbt_client = qbittorrentapi.Client(
              host=host,
              username=username,
              password=password
          )
  
          try:
              qbt_client.auth_log_in()
          except qbittorrentapi.LoginFailed as e:
              raise Exception(f"Failed to login to qBittorrent: {e}")
  
      return qbt_client