mcp-image-downloader
If you are the rightful owner of mcp-image-downloader and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Image Downloader MCP Server is a versatile tool for downloading and processing images with features like progress tracking, batch downloads, and image manipulation.
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
- 无代理(直接连接)
详细的代理使用说明请参考 。
进度跟踪
服务器提供详细的进度信息:
- 下载进度百分比
- 已下载/总字节数
- 下载速度
- 预计剩余时间
- 批量下载的整体进度
故障排除
常见问题
-
模块未找到错误
- 确保运行了
npm install
- 检查 MCP 配置中的路径是否正确
- 确保运行了
-
权限错误
- 确保对下载目录有写入权限
- 在 macOS 上可能需要授予应用程序文件访问权限
-
网络错误
- 检查网络连接
- 验证图片 URL 是否可访问
- 某些网站可能需要特定的 User-Agent
- 如果使用代理,确保代理服务器正常运行
-
代理连接问题
- 验证代理服务器地址和端口
- 检查代理认证信息是否正确
- 确保代理服务器支持目标协议
调试
启用详细日志:
DEBUG=* npm start
许可证
MIT