Image Downloader

🚀 图像下载器 MCP 服务器

这是一个支持图片下载和处理的 MCP（模型上下文协议）服务器，具备进度跟踪、批量下载和图片处理等功能，能有效满足用户对图片下载与处理的多样化需求。

🚀 快速开始

配置好 MCP 客户端后，就可以直接在支持 MCP 的应用中使用图片下载功能。若进行本地开发和测试，启动服务器可使用命令 npm start ；开发模式使用 npm run dev ；测试使用 npm test 或 npm run test:progress 。

✨ 主要特性

• 🖼️ 支持单张图片下载。
• 📦 支持批量图片下载。
• 🔄 提供实时进度跟踪。
• 🎨 支持图片格式转换（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

可配置的环境变量如下：

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 工具

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_PROXY 或 HTTPS_PROXY。
3. 无代理（直接连接）。

详细的代理使用说明请参考 PROXY_USAGE.md。

进度跟踪

服务器提供详细的进度信息，包括：

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

故障排除

常见问题

1. 模块未找到错误
   • 确保运行了 npm install。
   • 检查 MCP 配置中的路径是否正确。
2. 权限错误
   • 确保对下载目录有写入权限。
   • 在 macOS 上可能需要授予应用程序文件访问权限。
3. 网络错误
   • 检查网络连接。
   • 验证图片 URL 是否可访问。
   • 某些网站可能需要特定的 User - Agent。
   • 如果使用代理，确保代理服务器正常运行。
4. 代理连接问题
   • 验证代理服务器地址和端口。
   • 检查代理认证信息是否正确。
   • 确保代理服务器支持目标协议。

调试

启用详细日志：

DEBUG=* npm start

📄 许可证

本项目采用 MIT 许可证。