Image Downloader

🚀 圖片下載器 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

可配置的環境變量：

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_PROXY 或 HTTPS_PROXY
3. 無代理（直接連接）

詳細的代理使用說明請參考 PROXY_USAGE.md。

進度跟蹤

服務器提供詳細的進度信息：

• 下載進度百分比
• 已下載/總字節數
• 下載速度
• 預計剩餘時間
• 批量下載的整體進度

故障排除

常見問題

1. 模塊未找到錯誤

• 確保運行了 npm install
• 檢查 MCP 配置中的路徑是否正確

2. 權限錯誤

• 確保對下載目錄有寫入權限
• 在 macOS 上可能需要授予應用程序文件訪問權限

3. 網絡錯誤

• 檢查網絡連接
• 驗證圖片 URL 是否可訪問
• 某些網站可能需要特定的 User-Agent
• 如果使用代理，確保代理服務器正常運行

4. 代理連接問題

• 驗證代理服務器地址和端口
• 檢查代理認證信息是否正確
• 確保代理服務器支持目標協議

調試

啟用詳細日誌：

DEBUG=* npm start

📄 許可證

MIT