Download MCP

A high-performance file download tool based on the MCP (Model Context Protocol) standard, supporting multi-threaded downloads, resumable downloads, and session management.

✨ Features

🚀 Core Download Features

• Multi-threaded Downloads: Supports 1-16 concurrent connections, significantly improving download speed.
• Resumable Downloads: Automatically handles network interruptions and supports resuming from breakpoints.
• Real-time Monitoring: Provides detailed information on download progress, speed, and ETA.
• Smart Retry: Automatically retries failed download segments to increase success rates.
• Task Management: Complete list of download tasks with status queries.

🌐 Session Management

• Cookie Management: Automatically handles HTTP cookies and session states.
• Browser Simulation: Full headers and user-agent simulation.
• Pre-request Support: Establishes session state for websites requiring login.
• Multi-site Support: Supports download links that require specific session states.

🔧 Technical Features

• MCP Standard: Fully compatible with the MCP protocol, making it easy to integrate.
• TypeScript: Complete type safety and intelligent code hints.
• Persistent Storage: Automatically saves download state, allowing recovery after a restart.
• Cross-platform: Supports Windows, Linux, and macOS.

📦 Installation

bash

Clone the project

git clone
cd DownLoadMCP

Install dependencies

npm install

Build the project

npm run build

🚀 Quick Start

1. Start the Service

Windows

cmd

Use batch script

start.bat

Or start manually

npm start

Linux/macOS

bash

Use shell script

chmod +x start.sh
./start.sh

Or start manually

npm start

2. MCP Configuration

Basic Configuration

Add the following configuration to your MCP client:

json
{
"mcpServers": {
"download-mcp": {
"command": "node",
"args": ["./dist/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}

Cross-platform Path Configuration

Windows Example:
json
{
"mcpServers": {
"download-mcp": {
"command": "node",
"args": ["C:\Users\YourName\DownLoadMCP\dist\index.js"],
"env": {
"NODE_ENV": "production",
"PATH": "C:\Program Files\nodejs;%PATH%"
}
}
}
}

Linux/macOS Example:
json
{
"mcpServers": {
"download-mcp": {
"command": "node",
"args": ["/home/username/DownLoadMCP/dist/index.js"],
"env": {
"NODE_ENV": "production",
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}

Environment Variable Explanation:

• NODE_ENV: Set to production to enable production mode optimizations.
• PATH: Ensure the Node.js executable path is included in the environment variables.
  • Windows: Node.js is typically installed in C:\Program Files\nodejs.
  • Linux/macOS: Typically found in /usr/local/bin or /usr/bin.

Validation of Environment Variables:

1. Effect of NODE_ENV=production:

   • Enables Node.js production mode optimizations.
   • Disables development debugging information.
   • Improves performance and security.

2. Importance of PATH Environment Variable:

   • Ensures Claude Desktop can find the Node.js executable.
   • Avoids "node: command not found" errors.
   • Supports different Node.js installation paths.

3. Verify Configuration:
   bash

   Check if Node.js is in PATH

   node --version

   Check if npm is available

   npm --version

   Test if the project starts correctly

   cd /path/to/DownLoadMCP
   node dist/index.js

Key Points for Configuration:

• Use absolute paths to dist/index.js.
• Ensure Node.js is in the system PATH.
• Adjust path formats according to the operating system.

3. Claude Desktop Integration

Configuration File Location

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Complete Configuration Example

Windows:
json
{
"mcpServers": {
"download-mcp": {
"command": "node",
"args": ["C:\Users\YourName\DownLoadMCP\dist\index.js"],
"env": {
"NODE_ENV": "production",
"PATH": "C:\Program Files\nodejs;%PATH%"
}
}
}
}

Linux/macOS:
json
{
"mcpServers": {
"download-mcp": {
"command": "node",
"args": ["/home/username/DownLoadMCP/dist/index.js"],
"env": {
"NODE_ENV": "production",
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}## 🛠️ Available Tools

Core Download Tools

1. pre_request - Pre-request Tool

Establishes session state, handling websites that require login or specific sessions.

Parameters:

• url (required): The URL to access
• method (optional): HTTP method (GET, POST, HEAD, default GET)
• headers (optional): Additional request headers object
• body (optional): Request body content (used for POST requests)
• sessionId (optional): Session ID, if not provided, it will be auto-generated
• timeout (optional): Request timeout, default 30000ms
• followRedirects (optional): Whether to follow redirects, default true
• userAgent (optional): Custom User-Agent
• referer (optional): Set the Referer header

Return Value:
json
{
"success": true,
"sessionId": "session-uuid",
"statusCode": 200,
"headers": {...},
"cookies": [...],
"redirectHistory": [...]
}

2. download_file - File Download

The main file download tool, supporting multi-threading and session management.

Parameters:

• url (required): Download link
• outputPath (required): Output directory path
• filename (optional): Custom filename
• maxConcurrency (optional): Number of concurrent connections (1-16, default 4)
• chunkSize (optional): Chunk size, default 1048576 (1MB)
• timeout (optional): Request timeout, default 30000ms
• retryCount (optional): Retry count (0-10, default 3)
• workMode (optional): Work mode
  • blocking: Blocking mode, waits until the download is complete
  • non_blocking: Non-blocking mode, returns task ID immediately
  • persistent: Persistent mode
  • temporary: Temporary mode
• enableResume (optional): Enable resumable downloads, default true
• sessionId (optional): Use a pre-established session state
• headers (optional): Custom HTTP request headers

Return Value:
json
{
"success": true,
"taskId": "task-uuid",
"filename": "downloaded-file.zip",
"totalSize": 1048576,
"status": "downloading"
}

3. Task Management Tools

get_download_status - Query Download Status

Parameters:

• taskId (required): Unique identifier of the download task

Return Value:
json
{
"taskId": "task-uuid",
"status": "downloading",
"progress": 0.75,
"downloadedSize": 786432,
"totalSize": 1048576,
"speed": "1.2 MB/s",
"eta": "00:00:05",
"connections": 4
}

pause_download - Pause Download

Parameters:

• taskId (required): ID of the download task to pause

resume_download - Resume Download

Parameters:

• taskId (required): ID of the download task to resume

cancel_download - Cancel Download

Parameters:

• taskId (required): ID of the download task to cancel

list_downloads - List All Tasks

Parameters:

• status (optional): Filter by status (pending, downloading, paused, completed, failed, cancelled)
• limit (optional): Limit the number of tasks returned, default 20
• offset (optional): Pagination offset, default 0

4. verify_integrity - File Integrity Verification

Verifies the integrity of a file, supporting multiple hash algorithms.

Parameters:

• filePath (required): Path to the file to verify
• algorithm (optional): Hash algorithm (md5, sha1, sha256, sha512, default sha256)
• expectedChecksum (optional): Expected checksum value
• generateReport (optional): Whether to generate a detailed report, default false

Return Value:
json
{
"success": true,
"algorithm": "sha256",
"checksum": "abc123...",
"verified": true,
"fileSize": 1048576,
"processingTime": "0.5s"
}

⚙️ Configuration Recommendations

Connection Type	Concurrency	Chunk Size	Applicable Scenarios
Slow	1-2	256KB	<10Mbps
Medium	4-6	1MB	10-100Mbps
Fast	8-16	2-4MB	>100Mbps

🆚 Comparison with Other Tools

Feature	This Tool	aria2	wget	curl
Multi-threaded Download	✅	✅	❌	❌
Session Management	✅	❌	❌	✅
MCP Integration	✅	❌	❌	❌
Real-time Monitoring	✅	✅	❌	❌
Resumable Downloads	✅	✅	✅	✅

Solutions to Common Issues

1. Installation and Startup Issues

Issue: npm install fails
bash

Solution

Clear cache

npm cache clean --force

Remove node_modules and reinstall

rm -rf node_modules package-lock.json # Linux/macOS
rmdir /s node_modules & del package-lock.json # Windows
npm install

Issue: Build fails with npm run build
bash

Check TypeScript version

npx tsc --version

Reinstall TypeScript

npm install -D typescript@latest

Clean and rebuild

npm run clean
npm run build

Issue: Service startup failure
bash

Check Node.js version (requires >=18.0.0)

node --version

Check port usage

netstat -ano | findstr :3000 # Windows
lsof -i :3000 # Linux/macOS

Check file permissions (Linux/macOS)

chmod +x start.sh

2. MCP Configuration Issues

Issue: Claude Desktop cannot connect to the MCP server

• Check path: Ensure that the path in args is an absolute path.
• Check permissions: Ensure that Claude Desktop has permission to access the files.
• Check Node.js: Ensure that Node.js is included in the system PATH.

Windows configuration example:
json
{
"mcpServers": {
"download-mcp": {
"command": "C:\Program Files\nodejs\node.exe",
"args": ["C:\Users\YourName\DownLoadMCP\dist\index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}

3. Download Issues

Issue: Unable to download from a site that requires login
javascript
// Solution: Use pre_request to establish a session
// 1. First, establish the session
{
"tool": "pre_request",
"url": "https://site.com/login",
"method": "POST",
"body": "username=user&password=pass"
}

// 2. Use the returned sessionId to download
{
"tool": "download_file",
"url": "https://site.com/protected-file.zip",
"outputPath": "./downloads",
"sessionId": "Session ID returned from step 1"
}

Issue: Slow download speed

• Increase concurrency: Set maxConcurrency to 8-16.
• Adjust chunk size: For high-speed networks, use a chunkSize of 2-4MB.
• Check network: Use a network speed test tool to check bandwidth.
• Server limitations: Some servers limit the number of connections per IP.

Issue: Connection timeout
json
{
"tool": "download_file",
"url": "https://example.com/file.zip",
"outputPath": "./downloads",
"timeout": 60000,
"retryCount": 5,
"maxConcurrency": 2
}

Issue: Resume download fails

• Check disk space: Ensure there is enough storage space.
• Check file permissions: Ensure you have write permissions.
• Clean state files: Delete the .download-resume/ directory and start over.

4. File Integrity Issues

Issue: Checksum mismatch
json
{
"tool": "verify_integrity",
"filePath": "./downloads/file.zip",
"algorithm": "sha256",
"expectedChecksum": "abc123..."
}

Issue: Downloaded file is corrupted

• Redownload: Delete the partially downloaded file and start over.
• Change download source: Try a different download link.
• Check network stability: Use a wired connection instead of wireless.

5. Performance Optimization

For slow networks (<10Mbps):
json
{
"maxConcurrency": 2,
"chunkSize": 262144,
"timeout": 60000,
"retryCount": 5
}

For high-speed networks (>100Mbps):
json
{
"maxConcurrency": 16,
"chunkSize": 4194304,
"timeout": 30000,
"retryCount": 3
}

6. Logging and Debugging

Enable detailed logging:
bash

Set environment variable

export DEBUG=download-mcp:* # Linux/macOS
set DEBUG=download-mcp:* # Windows

Start the service

npm start

View download status:
json
{
"tool": "list_downloads",
"status": "failed"
}

Get task details:
json
{
"tool": "get_download_status",
"taskId": "your-task-id"
}

📄 License

MIT License

---

🎉 You now have a fully functional and high-performance download tool!