金大哥 - Image Downloader MCP 详情

article

README

🚀 图片下载器 MCP 服务器

这是一个支持图片下载和处理的 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 (必需): 图片 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"
}

代理支持

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

代理配置方式

环境变量配置（全局默认）：

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