Image Downloader
by
Downloads images from URLs with support for batch operations, format conversion, resizing, compression, progress tracking, and proxy configuration.
Image Downloader Overview
Image Downloader
What is Image Downloader about?
Image Downloader provides a Model Context Protocol (MCP) server that fetches images from remote URLs, optionally processes them (change format, resize, compress), and stores them locally. It includes real‑time progress reporting and can operate behind HTTP/HTTPS/SOCKS5 proxies.
How to use Image Downloader?
- Run via npx (recommended)
npx mcp-image-downloader - Configure environment variables by copying
.env.exampleto.envand adjusting values such asDEFAULT_SAVE_PATH,DEFAULT_FORMAT,DEFAULT_COMPRESS, etc. - Add an MCP client entry (e.g., Cursor IDE or Claude Desktop) pointing to the npx command. Example for Cursor:
{ "mcpServers": { "image-downloader": { "command": "npx", "args": ["mcp-image-downloader"], "env": { "DEFAULT_SAVE_PATH": "/Users/username/Downloads/images", "DEFAULT_FORMAT": "jpeg", "DEFAULT_COMPRESS": "true", "DEFAULT_MAX_WIDTH": "1920", "DEFAULT_MAX_HEIGHT": "1080", "DEFAULT_CONCURRENCY": "5", "HTTP_PROXY": "http://proxy.example.com:8080", "HTTPS_PROXY": "http://proxy.example.com:8080" } } } } - Invoke MCP tools from your client:
download_image– single image download.download_images_batch– batch download with concurrency control.
Key features of Image Downloader
- Single and batch image downloading.
- Real‑time progress percentages, speed, and ETA.
- Format conversion to JPEG, PNG, WebP, or keep original.
- Optional resizing (max width / height) and compression.
- Proxy support (HTTP, HTTPS, SOCKS5) via environment variables or per‑call parameter.
- Concurrency control for batch jobs (1‑10 concurrent downloads).
- Fully configurable via
.envand MCP client JSON.
Use cases of Image Downloader
- Content aggregation: collect large sets of images for training datasets or web archives.
- Automation scripts: embed into CI pipelines to fetch assets before builds.
- Research: gather images from public URLs while tracking download progress.
- Team workflows: integrate with Cursor IDE or Claude Desktop to let AI assistants retrieve and preprocess images on demand.
FAQ from the Image Downloader
Q: Do I need to install the package locally?
A: No. The recommended npx approach runs the latest version without a permanent installation.
Q: How do I change the default save directory?
A: Set DEFAULT_SAVE_PATH in the .env file or pass savePath in the tool parameters.
Q: Can I download through a proxy that requires authentication?
A: Yes. Use URLs like http://user:pass@proxy.example.com:8080 in HTTP_PROXY/HTTPS_PROXY or the proxy argument.
Q: What image formats are supported for conversion?
A: jpeg, png, webp, or original to keep the source format.
Q: How is concurrency limited?
A: Via the DEFAULT_CONCURRENCY env variable or the concurrency argument (range 1‑10).
Q: How can I see detailed logs?
A: Run the server with DEBUG=* npm start to output verbose debugging information.
Image Downloader's README
Image Downloader MCP Server
一个支持图片下载和处理的 MCP (Model Context Protocol) 服务器，具有进度跟踪、批量下载和图片处理功能。
功能特性
- 🖼️ 单张图片下载
- 📦 批量图片下载
- 🔄 实时进度跟踪
- 🎨 图片格式转换 (JPEG, PNG, WebP)
- 📏 图片尺寸调整
- 🗜️ 图片压缩
- 🌐 代理服务器支持
- ⚙️ 环境变量配置支持
安装
方式一：通过 npx 安装（推荐）
直接使用 npx 运行，无需本地安装：
npx mcp-image-downloader
方式二：全局安装
npm install -g mcp-image-downloader
方式三：本地开发安装
git clone https://github.com/cced3000/mcp-image-downloader.git
cd mcp-image-downloader
npm install
npx 的优势
使用 npx 方式有以下优势：
- ✅ 无需本地安装，始终使用最新版本
- ✅ 自动处理依赖关系
- ✅ 减少本地存储空间占用
- ✅ 避免版本冲突问题
- ✅ 配置更简单，无需指定路径
配置
环境变量配置
复制 .env.example 到 .env 并根据需要修改配置：
cp .env.example .env
可配置的环境变量：
| 环境变量 | 描述 | 默认值 | 示例 |
|---|---|---|---|
DEFAULT_SAVE_PATH |
默认下载目录 | ./downloads |
/Users/username/Pictures |
DEFAULT_FILENAME |
默认文件名模式 | 原始文件名 | image_{timestamp} |
DEFAULT_FORMAT |
默认图片格式 | original |
jpeg, png, webp |
DEFAULT_COMPRESS |
默认压缩设置 | false |
true, false |
DEFAULT_MAX_WIDTH |
默认最大宽度 | 无限制 | 1920 |
DEFAULT_MAX_HEIGHT |
默认最大高度 | 无限制 | 1080 |
DEFAULT_CONCURRENCY |
默认并发数 | 3 |
1-10 |
HTTP_PROXY |
HTTP 代理服务器 | 无 | http://proxy.example.com:8080 |
HTTPS_PROXY |
HTTPS 代理服务器 | 无 | http://proxy.example.com:8080 |
MCP 客户端配置
Cursor IDE 配置
使用 npx（推荐）：
在 .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"
}
}
}
}
使用本地安装：
{
"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 配置
使用 npx（推荐）：
在 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"
}
}
}
}
使用本地安装：
{
"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"
}
}
}
}
使用方法
通过 MCP 客户端使用
配置好 MCP 客户端后，可以直接在支持 MCP 的应用中使用图片下载功能。
本地开发和测试
启动服务器
npm start
开发模式
npm run dev
测试
# 运行所有测试
npm test
# 测试进度跟踪
npm run test:progress
MCP 工具
download_image
下载单张图片。
参数：
url(必需): 图片 URLsavePath(可选): 保存目录，默认使用环境变量配置filename(可选): 自定义文件名format(可选): 输出格式 (jpeg, png, webp, original)compress(可选): 是否压缩maxWidth(可选): 最大宽度maxHeight(可选): 最大高度proxy(可选): 代理服务器 URL
示例：
{
"url": "https://example.com/image.jpg",
"format": "webp",
"compress": true,
"maxWidth": 800,
"proxy": "http://proxy.example.com:8080"
}
download_images_batch
批量下载图片。
参数：
urls(必需): 图片 URL 数组savePath(可选): 保存目录format(可选): 输出格式compress(可选): 是否压缩maxWidth(可选): 最大宽度maxHeight(可选): 最大高度proxy(可选): 代理服务器 URLconcurrency(可选): 并发下载数 (1-10)proxy(可选): 代理服务器 URL
示例：
{
"urls": [
"https://example.com/image1.jpg",
"https://example.com/image2.png"
],
"format": "jpeg",
"concurrency": 3,
"proxy": "http://proxy.example.com:8080"
}
代理支持
服务器支持通过代理服务器下载图片，适用于需要通过代理访问网络的环境。
代理配置方式
-
环境变量配置（全局默认）：
export HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 # 带认证的代理 export HTTP_PROXY=http://username:password@proxy.example.com:8080 -
参数配置（单次使用）： 在调用工具时通过
proxy参数指定
支持的代理格式
http://proxy.example.com:8080- 基本 HTTP 代理https://proxy.example.com:8080- HTTPS 代理http://username:password@proxy.example.com:8080- 带认证的代理socks5://proxy.example.com:1080- SOCKS5 代理
代理优先级
- 函数调用时的
proxy参数（最高优先级） - 环境变量
HTTP_PROXY或HTTPS_PROXY - 无代理（直接连接）
详细的代理使用说明请参考 PROXY_USAGE.md。
进度跟踪
服务器提供详细的进度信息：
- 下载进度百分比
- 已下载/总字节数
- 下载速度
- 预计剩余时间
- 批量下载的整体进度
故障排除
常见问题
-
模块未找到错误
- 确保运行了
npm install - 检查 MCP 配置中的路径是否正确
- 确保运行了
-
权限错误
- 确保对下载目录有写入权限
- 在 macOS 上可能需要授予应用程序文件访问权限
-
网络错误
- 检查网络连接
- 验证图片 URL 是否可访问
- 某些网站可能需要特定的 User-Agent
- 如果使用代理，确保代理服务器正常运行
-
代理连接问题
- 验证代理服务器地址和端口
- 检查代理认证信息是否正确
- 确保代理服务器支持目标协议
调试
启用详细日志：
DEBUG=* npm start
许可证
MIT
赞助商
Image Downloader Reviews
Login Required
Please log in to share your review and rating for this MCP.
Similar MCP Servers like Image Downloader
Explore related MCPs that share similar capabilities and solve comparable challenges
Fetch
Officialby modelcontextprotocol
A Model Context Protocol server that provides web content fetching capabilities.
Playwright MCP
Officialby microsoft
Provides fast, lightweight browser automation using Playwright's accessibility tree, enabling LLMs to interact with web pages through structured snapshots instead of screenshots.
Firecrawl MCP Server
by firecrawl
Provides powerful web scraping capabilities for LLM clients such as Cursor, Claude, and others, enabling content extraction, crawling, search, and batch processing through a Model Context Protocol server.
Firecrawl MCP Server
by firecrawl
Provides web scraping, crawling, search, and structured data extraction for LLM clients through a Model Context Protocol server.
Bb Browser
by epiral
Enables AI agents to interact with any website through the user's logged‑in Chrome instance, exposing site‑specific commands via a CLI or MCP server.
Web MCP
Officialby brightdata
Provides real-time web access for AI models, delivering search, markdown‑ready scraping, and optional browser automation while bypassing geo‑restrictions, rate limits, and CAPTCHAs.
Tavily MCP
by tavily-ai
Provides real‑time web search, intelligent data extraction, structured website mapping, and systematic crawling through an MCP server, ready to be integrated with AI coding assistants and other tools.
Fetch MCP Server
by zcaceres
Fetches web content and returns it in HTML, JSON, plain‑text, or Markdown formats, optionally applying custom request headers.
Hyperbrowser MCP Server
by hyperbrowserai
Provides tools to scrape, extract structured data, crawl webpages, and access general‑purpose browser agents such as OpenAI CUA, Anthropic Claude Computer Use, and lightweight Browser Use via a Model Context Protocol server.