mcp-image-downloader

mcp-image-downloader

3.4

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默认图片格式originaljpeg, png, webp
DEFAULT_COMPRESS默认压缩设置falsetrue, false
DEFAULT_MAX_WIDTH默认最大宽度无限制1920
DEFAULT_MAX_HEIGHT默认最大高度无限制1080
DEFAULT_CONCURRENCY默认并发数31-10
HTTP_PROXYHTTP 代理服务器http://proxy.example.com:8080
HTTPS_PROXYHTTPS 代理服务器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 (必需): 图片 URL
  • savePath (可选): 保存目录,默认使用环境变量配置
  • 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 (可选): 代理服务器 URL
  • concurrency (可选): 并发下载数 (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"
}

代理支持

服务器支持通过代理服务器下载图片,适用于需要通过代理访问网络的环境。

代理配置方式

  1. 环境变量配置(全局默认)

    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
    
  2. 参数配置(单次使用): 在调用工具时通过 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 代理

代理优先级

  1. 函数调用时的 proxy 参数(最高优先级)
  2. 环境变量 HTTP_PROXYHTTPS_PROXY
  3. 无代理(直接连接)

详细的代理使用说明请参考

进度跟踪

服务器提供详细的进度信息:

  • 下载进度百分比
  • 已下载/总字节数
  • 下载速度
  • 预计剩余时间
  • 批量下载的整体进度

故障排除

常见问题

  1. 模块未找到错误

    • 确保运行了 npm install
    • 检查 MCP 配置中的路径是否正确
  2. 权限错误

    • 确保对下载目录有写入权限
    • 在 macOS 上可能需要授予应用程序文件访问权限
  3. 网络错误

    • 检查网络连接
    • 验证图片 URL 是否可访问
    • 某些网站可能需要特定的 User-Agent
    • 如果使用代理,确保代理服务器正常运行
  4. 代理连接问题

    • 验证代理服务器地址和端口
    • 检查代理认证信息是否正确
    • 确保代理服务器支持目标协议

调试

启用详细日志:

DEBUG=* npm start

许可证

MIT