Image Downloader

画像ダウンローダー MCP サーバー

進捗追跡、一括ダウンロード、画像処理機能を備えた、画像のダウンロードと処理に対応する MCP（Model Context Protocol）サーバーです。

主な機能

• 🖼️ 画像のダウンロード（1 枚）
• 📦 画像の一括ダウンロード
• 🔄 リアルタイムの進捗追跡
• 🎨 画像形式の変換（JPEG、PNG、WebP）
• 📏 画像サイズの変更
• 🗜️ 画像の圧縮
• 🌐 プロキシサーバーのサポート
• ⚙️ 環境変数による設定のサポート

インストール

方法 1：npx でインストール（推奨）

ローカルにインストールせず、npx を使って直接実行できます。

npx mcp-image-downloader

方法 2：グローバルインストール

npm install -g mcp-image-downloader

方法 3：ローカル開発用インストール

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

画像を 1 枚ダウンロードします。

パラメーター：

• 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:[email protected]:8080
   

2. パラメーターで設定（1 回限りの使用）： ツールの呼び出し時に proxy パラメーターを指定します。

対応するプロキシ形式

• http://proxy.example.com:8080 - 基本的な HTTP プロキシ
• https://proxy.example.com:8080 - HTTPS プロキシ
• http://username:[email protected]: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