Image Downloader

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

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

🚀 クイックスタート

このサーバーを使用することで、画像のダウンロードと処理を簡単に行うことができます。以下の手順に従って、サーバーをセットアップしてください。

✨ 主な機能

• 🖼️ 単一画像のダウンロード
• 📦 画像の一括ダウンロード
• 🔄 リアルタイムの進捗追跡
• 🎨 画像フォーマットの変換（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

設定可能な環境変数は以下の通りです。

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ライセンスの下で公開されています。