Wajeeha Download Manager

A fast download manager for Windows with multi-connection accelerated downloads, dynamic segmentation, pause/resume, categories, queues with a scheduler, a site grabber, batch downloads, ZIP preview, a speed limiter, browser extensions, and support for AI agents through the Model Context Protocol (MCP).

Main Screenshot

Related MCP server: GPT-to-Windows

Other Screenshots

Contents

1. Quick start

2. Build the .exe

3. Browser extension

4. HTTPS certificate errors

5. Using the app

6. AI agents (MCP)

7. How it works

8. Limitations

9. Project layout

1. Quick start

Requirements: Windows and Python 3.10 or newer.

1. Unzip the folder anywhere.

2. Double-click setup_and_run.bat. It installs PySide6 once, then starts the app.

   Or run it yourself in a Command Prompt inside the folder:

   pip install -r requirements.txt
   python main.py

On first start the app creates these folders inside your Windows Downloads folder:

Compressed   Documents   Images   Music   Programs   Video

Files that don't match a category stay in the Downloads folder itself. You can change the folders and file types at any time under Options > Save to, or by right-clicking a category.

2. Build the .exe

Double-click build_exe.bat. It creates a dist folder containing:

Copy them together wherever you want.

Windows SmartScreen may warn about an unsigned exe the first time you run it. Choose More info > Run anyway.

3. Browser extension

Install it once per browser. The app must be running (it can sit in the system tray).

Chrome / Edge / Brave / Opera / Vivaldi

1. Open the extensions page: chrome://extensions (or edge://extensions, etc.).

2. Turn on Developer mode.

3. Click Load unpacked and choose the extension folder.

Tip: in the app, Help > Browser integration shows the exact folder path.

Firefox

1. Open about:debugging#/runtime/this-firefox.

2. Click Load Temporary Add-on and choose extension\manifest.json.

3. In about:addons, open the extension's Permissions and allow Access your data for all websites.

Firefox forgets temporary add-ons when it closes. A permanent install needs a signed add-on or Firefox Developer Edition.

What the extension does

• Takes over downloads of the file types listed in Options > Browser.

• Right-click a link, image, or video: Download with Wajeeha DM.

• Right-click a page: Download files from this page (Grabber).

• Shows a Download this video button over videos, and lists the media it saw in its popup (the blue number on the toolbar icon).

• Hold Alt while clicking a link to let the browser download it normally.

• If the app is not running, the browser just downloads as usual.

Updating

If you update the app, also update the extension. Open the extensions page and click the circular Reload arrow on the Wajeeha extension (or remove it and Load unpacked again), then refresh any open tabs.

If the extension says it can't reach the app

1. Look at the bottom-right of the app window. It should say Browser link: port 49875, extension connected. If it says waiting for the browser extension, the extension has not reached the app yet.

2. Click the extension's toolbar icon. The top line shows the exact reason (for example port 49875: Failed to fetch) plus a Check again button.

3. Make sure the extension has permission for all sites, and that no security software blocks 127.0.0.1 (localhost) connections.

4. Still stuck? Check %APPDATA%\WajeehaDownloadManager\app.log for details.

4. HTTPS certificate errors

Some sites open fine in your browser but fail in the app with a certificate message. The browser uses Windows' own certificate checker, which fetches missing certificates by itself. Since v1.0.2 the app uses that same Windows checker (the truststore package, installed by setup_and_run.bat and build_exe.bat), so most of these errors disappear.

After updating, run setup_and_run.bat again and rebuild the exe.

If a site still can't be verified, the message says why:

To continue anyway for one file: right-click it, choose Properties, tick Don't verify this site's HTTPS certificate, then Resume. (In the New download window the same tick appears automatically.)

A global switch exists in Options > Connection. Only use it on a network you trust, because it also hides tampering.

5. Using the app

6. AI agents (MCP)

Tell your AI agent "download https://example.com/file.zip" and it hands the job to Wajeeha Download Manager: fast, resumable, and sorted into your category folders.

The app speaks the Model Context Protocol (MCP), so any MCP-capable app can use it. Both the older (initialize) and the newer stateless (2026-07-28, server/discover) versions of the protocol are supported.

Set it up (one time)

Open the app, then Help > AI agents (MCP) (or Options > AI agents). Pick your AI app from the list. The box shows text already filled in with your paths and your private access token. Click Copy, then:

Claude Code — run the command in a terminal, then check with claude mcp list:

claude mcp add --scope user --transport stdio wajeeha -- "C:\path\wajeeha-mcp.exe"

The HTTP variant works too, but the app must already be running. The stdio variant starts the app by itself, hidden in the tray, the first time it's needed.

Claude Desktop — go to Settings > Developer > Edit Config, add the shown JSON under "mcpServers", save, and restart Claude Desktop.

Cursor / VS Code / others — use the HTTP settings text (URL plus an Authorization header).

Running from source (not the exe)? The snippets then use python wajeeha_mcp.py.

What the agent can do

The agent gets 13 tools:

It also gets 3 read-only resources (download list, categories, status) and 3 ready-made prompts (download, download_from_page, download_status).

Downloads started by an agent are marked AI agent: <name> in the Description column.

Safety

All of this is enforced inside the app, not left to the agent.

• Only http, https, and ftp links are accepted. Files go only into your Downloads folders (tricks like .., other drives, or symlinks are blocked) unless you allow more.

• The app asks you (Allow / Deny window) before:

  • downloading programs or scripts (.exe, .msi, .bat, …),

  • using addresses on this PC or your local network,

  • switching certificate checks off,

  • saving outside Downloads.

  Change this in Options > AI agents (risky only / always / never). No answer within 2 minutes counts as Deny.

• An agent can never delete a finished file, read your files, or change other settings.

• The HTTP endpoint needs your private token, only accepts connections from this PC, and refuses anything that comes from a web page.

• Create a new access token in Options > AI agents locks out everything using the old one.

• To switch the whole feature off, untick Let AI agents (MCP) download files.

If it doesn't work

• In Claude Code, run /mcp to see the server's status and error text.

• Can't reach / not running: open the app once and check that Options > AI agents is ticked.

• Rejected the access token: restart that MCP entry (the stdio helper re-reads the token by itself).

• Details are written to %APPDATA%\WajeehaDownloadManager\app.log.

7. How it works

• Dynamic segmentation ("in-half rule"). A download starts as one piece on one connection. Each extra connection takes the largest unfinished piece and splits it in half, so every connection stays busy until the very end.

• Resume. All piece positions are saved every few seconds, so after a stop, crash, or power cut the download resumes. While downloading, a <name>.wdmpart file sits beside the target; it is renamed to the real name when finished.

• Categories. Each has a name, folder, file types, and optional sites. The category is picked from the file name, or from the server's real name after probing.

• Browser link. The extension talks to the app over http://127.0.0.1:49875-49879. Web pages can't use it: requests from a normal web page are refused, and the app only listens on your own computer. The status bar (bottom right) shows extension connected once your browser extension has contacted the app.

8. Limitations

• HLS/DASH streaming playlists (.m3u8 / .mpd) and sites that split video and audio (e.g. YouTube) can't be downloaded or merged. The extension lists them but marks them not supported yet.

• Not supported: Safari integration, dial-up/VPN redial, download quotas, SOCKS proxies, toolbar skins, and the MMS protocol.

• Connections are opened per piece; reusing keep-alive connections would be a speed-up.

• Site-login passwords are stored in plain text in the settings file: %APPDATA%\WajeehaDownloadManager\settings.json.

• FTP is implemented (resume with REST) but was not tested against a real FTP server.

9. Project layout

main.py             starts the app
wajeeha_mcp.py      AI-agent helper (becomes wajeeha-mcp.exe)
wdm/
  engine.py         download engine
  server.py         browser link + /mcp endpoint
  grabber.py        site grabber + batch patterns
  mcp.py            MCP server
  agent.py          rules for what agents may do
  mcp_relay.py      stdio relay for MCP clients
  ui/               windows, dialogs, theme
extension/          browser extension
tests/              engine/bridge tests (python tests\test_engine.py)

Data locations