mcp-download

This MCP server exposes a download management service for AI agents via the MCP protocol. It allows AI models to initiate file downloads, monitor progress, manage tasks, and control multi-threaded downloads with features like pause, resume, cancel, and persistent background execution. The tool leverages a Python bridge script (bridging_download_mcp.py) to interact with a download engine that supports multi-threading (up to 32 threads), breakpoint resume, and real-time status metrics such as speed, progress, and estimated remaining time. You can instruct the agent to list tasks, start new downloads from URLs, adjust thread counts, and enable persistence so tasks survive restarts.

Typical interactions include: downloading a file from a URL, querying the status of a specific download ID, pausing or resuming downloads, scaling the number of threads for a given task, canceling active downloads, and cleaning up completed tasks. Advanced usage demonstrates starting a persistent download or using a high-thread-count operation for large files. The MCP interface encodes these operations in structured requests and returns standardized results for easy consumption by AI agents.

Prerequisites

• Git
• Node.js 18.x (for building/CLI tooling in this project, if applicable)
• Python 3.11 or higher (required for the Python-based bridging script)
• npm (comes with Node.js)

Installation steps

1. Clone the repository

git clone https://github.com/shuakami/mcp-download.git
cd mcp-download

2. Install dependencies and build (Node.js tooling)

npm install
npm run build

3. Ensure Python environment is ready

• Install Python 3.11+ and add to PATH
• Optional: create a virtual environment

4. Prepare the MCP bridge for Cursor integration

• The MCP server is invoked via Python using bridging_download_mcp.py. Ensure the script exists at the project root or adjust the path in mcp_config accordingly.

5. Run the MCP bridge for testing (optional)

python3 bridging_download_mcp.py

Notes

• The exact integration path may vary if you adapt the bridge location. The example config assumes bridging_download_mcp.py is at project root.

Tips and common questions:

• Environment variables: PYTHONUNBUFFERED=1 helps ensure real-time log output when connected to MCP clients.
• If the download engine requires authentication or proxies, you can extend the environment or provide URL-level credentials in MCP requests.
• For Windows paths in MCP configuration, use forward slashes or proper escaping as shown in examples; prefer absolute paths when possible for reliability.
• The persistence feature keeps tasks running in the background. If you rely on persistence, ensure the host environment has stable storage and sufficient permissions.
• When debugging, start the bridge script directly (python3 bridging_download_mcp.py) to verify basic MCP interactions before wiring through Cursor.
• If you encounter issues with multi-threading limits, confirm the underlying network and system constraints allow the specified number of concurrent connections.