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 (必需): 图片 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:[email protected]:8080

参数配置（单次使用）：在调用工具时通过 proxy 参数指定

支持的代理格式

http://proxy.example.com:8080 - 基本 HTTP 代理
https://proxy.example.com:8080 - HTTPS 代理
http://username:[email protected]: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