Image Downloader

🚀 Image Downloader MCP Server

An MCP (Model Context Protocol) server that supports image downloading and processing, featuring progress tracking, batch downloading, and image processing capabilities.

✨ Features

• 🖼️ Download a single image
• 📦 Download multiple images in batches
• 🔄 Track real-time progress
• 🎨 Convert image formats (JPEG, PNG, WebP)
• 📏 Resize images
• 🗜️ Compress images
• 🌐 Support proxy servers
• ⚙️ Support environment variable configuration

📦 Installation

Method 1: Install via npx (Recommended)

Run directly using npx without local installation:

npx mcp-image-downloader

Method 2: Global Installation

npm install -g mcp-image-downloader

Method 3: Local Development Installation

git clone https://github.com/cced3000/mcp-image-downloader.git
cd mcp-image-downloader
npm install

Advantages of npx

Using npx has the following advantages:

• ✅ No local installation required, always use the latest version
• ✅ Automatically handle dependencies
• ✅ Reduce local storage space usage
• ✅ Avoid version conflict issues
• ✅ Easier configuration, no need to specify paths

Configuration

Environment Variable Configuration

Copy .env.example to .env and modify the configuration as needed:

cp .env.example .env

Configurable environment variables:

MCP Client Configuration

Cursor IDE Configuration

Using npx (Recommended): Add the following to .cursor/mcp.json:

{
  "mcpServers": {
    "image-downloader": {
      "command": "npx",
      "args": ["mcp-image-downloader"],
      "env": {
        "DEFAULT_SAVE_PATH": "/Users/username/Downloads/images",
        "DEFAULT_FORMAT": "jpeg",
        "DEFAULT_COMPRESS": "true",
        "HTTPS_PROXY": "http://proxy.example.com:8080",
        "DEFAULT_MAX_WIDTH": "1920",
        "DEFAULT_MAX_HEIGHT": "1080",
        "DEFAULT_CONCURRENCY": "5",
        "HTTP_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

Using local installation:

{
  "mcpServers": {
    "image-downloader": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "/path/to/testmcp",
      "env": {
        "DEFAULT_SAVE_PATH": "/Users/username/Downloads/images",
        "DEFAULT_FORMAT": "jpeg",
        "DEFAULT_COMPRESS": "true",
        "HTTPS_PROXY": "http://proxy.example.com:8080",
        "DEFAULT_MAX_WIDTH": "1920",
        "DEFAULT_MAX_HEIGHT": "1080",
        "DEFAULT_CONCURRENCY": "5",
        "HTTP_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

Claude Desktop Configuration

Using npx (Recommended): Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "image-downloader": {
      "command": "npx",
      "args": ["mcp-image-downloader"],
      "env": {
        "DEFAULT_SAVE_PATH": "/Users/username/Downloads/images",
        "DEFAULT_FORMAT": "jpeg",
        "DEFAULT_COMPRESS": "true",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

Using local installation:

{
  "mcpServers": {
    "image-downloader": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "/path/to/testmcp",
      "env": {
        "DEFAULT_SAVE_PATH": "/Users/username/Downloads/images",
        "DEFAULT_FORMAT": "jpeg",
        "DEFAULT_COMPRESS": "true",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

💻 Usage Examples

Using via MCP Client

After configuring the MCP client, you can directly use the image download function in MCP-supported applications.

Local Development and Testing

Start the Server

npm start

Development Mode

npm run dev

Testing

# Run all tests
npm test

# Test progress tracking
npm run test:progress

📚 Documentation

download_image

Download a single image.

Parameters:

• url (Required): Image URL
• savePath (Optional): Save directory, defaulting to the environment variable configuration
• filename (Optional): Custom filename
• format (Optional): Output format (jpeg, png, webp, original)
• compress (Optional): Whether to compress
• maxWidth (Optional): Maximum width
• maxHeight (Optional): Maximum height
• proxy (Optional): Proxy server URL

Example:

{
  "url": "https://example.com/image.jpg",
  "format": "webp",
  "compress": true,
  "maxWidth": 800,
  "proxy": "http://proxy.example.com:8080"
}

download_images_batch

Download multiple images in batches.

Parameters:

• urls (Required): Array of image URLs
• savePath (Optional): Save directory
• format (Optional): Output format
• compress (Optional): Whether to compress
• maxWidth (Optional): Maximum width
• maxHeight (Optional): Maximum height
• proxy (Optional): Proxy server URL
• concurrency (Optional): Number of concurrent downloads (1-10)
• proxy (Optional): Proxy server URL

Example:

{
  "urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.png"
  ],
  "format": "jpeg",
  "concurrency": 3,
  "proxy": "http://proxy.example.com:8080"
}

Proxy Support

The server supports downloading images through a proxy server, suitable for environments where network access requires a proxy.

Proxy Configuration Methods

1. Environment Variable Configuration (Global Default):

   export HTTP_PROXY=http://proxy.example.com:8080
   export HTTPS_PROXY=http://proxy.example.com:8080
   
   # Proxy with authentication
   export HTTP_PROXY=http://username:password@proxy.example.com:8080
   

2. Parameter Configuration (Single Use): Specify the proxy parameter when calling the tool.

Supported Proxy Formats

• http://proxy.example.com:8080 - Basic HTTP proxy
• https://proxy.example.com:8080 - HTTPS proxy
• http://username:password@proxy.example.com:8080 - Proxy with authentication
• socks5://proxy.example.com:1080 - SOCKS5 proxy

Proxy Priority

1. The proxy parameter in the function call (Highest priority)
2. Environment variables HTTP_PROXY or HTTPS_PROXY
3. No proxy (Direct connection)

For detailed proxy usage instructions, please refer to PROXY_USAGE.md.

Progress Tracking

The server provides detailed progress information:

• Download progress percentage
• Downloaded/total bytes
• Download speed
• Estimated remaining time
• Overall progress of batch downloads

Troubleshooting

Common Issues

1. Module not found error
   • Ensure that npm install has been run.
   • Check the paths in the MCP configuration.
2. Permission error
   • Ensure that you have write permissions for the download directory.
   • On macOS, you may need to grant the application file access permissions.
3. Network error
   • Check the network connection.
   • Verify that the image URL is accessible.
   • Some websites may require a specific User-Agent.
   • If using a proxy, ensure that the proxy server is running properly.
4. Proxy connection issue
   • Verify the proxy server address and port.
   • Check the proxy authentication information.
   • Ensure that the proxy server supports the target protocol.

Debugging

Enable detailed logging:

DEBUG=* npm start

📄 License

MIT