Stock Images MCP

Stock Images MCP

Pexels、Unsplash、Pixabay からストック画像を検索、ダウンロードする MCP（Model Context Protocol）サーバーです。

機能

• search_images：設定済みのプロバイダーを1つ、またはすべて検索します。一部のプロバイダーで失敗した場合は、プロバイダーごとに報告されます
• download_image：画像をローカルフォルダーに安全にダウンロードします

セットアップ

API キーを取得する（最低1つ必要）

プロバイダー	環境変数	キーの取得先
Pexels	PEXELS_API_KEY	https://www.pexels.com/api/
Unsplash	UNSPLASH_API_KEY	https://unsplash.com/developers
Pixabay	PIXABAY_API_KEY	https://pixabay.com/api/docs/

任意：STOCK_IMAGES_DOWNLOAD_DIR — download_image がファイルを書き込む場所です（デフォルトは ./downloads）。

Claude Code / Cursor / Claude Desktop

MCP 設定（~/.claude/mcp.json、~/.cursor/mcp.json、または claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "stock-images": {
      "command": "npx",
      "args": ["-y", "stock-images-mcp"],
      "env": {
        "PEXELS_API_KEY": "your-key-here",
        "UNSPLASH_API_KEY": "your-key-here",
        "PIXABAY_API_KEY": "your-key-here"
      }
    }
  }
}

Node.js 22 以降が必要です。

Docker

docker build -t stock-images-mcp .
docker run -i --rm -e PEXELS_API_KEY=xxx -v "$PWD/downloads:/downloads" stock-images-mcp

ソースから

git clone https://github.com/jeanpfs/stock-images-mcp.git
cd stock-images-mcp
npm ci && npm run build
PEXELS_API_KEY=xxx node dist/index.js

ツール

search_images

設定済みのプロバイダーからストック画像を検索します。

パラメーター：

• query（必須）：検索語
• provider："pexels"、"unsplash"、"pixabay"、または "all"（デフォルト："all"）
• count：プロバイダーごとの結果数（デフォルトは5、最大20）
• orientation："landscape"、"portrait"、または "square"

各結果には id、provider、url、thumbnail、description、author、authorUrl、downloadUrl、width、height が含まれます。downloadUrl を download_image に渡してください。

download_image

画像をダウンロードディレクトリにダウンロードします。

パラメーター：

• url（必須）：pexels.com、unsplash.com、または pixabay.com 上の https 画像 URL（search_images の downloadUrl を使用）
• filename：出力ファイル名。使用できるのは英字、数字、_、-、. のみです。拡張子がない場合は、コンテンツタイプから追加されます（省略時は自動生成）
• folder：ダウンロードディレクトリ内のサブフォルダー

動作と制限：

• ダウンロードディレクトリは ./downloads、または設定されている場合は STOCK_IMAGES_DOWNLOAD_DIR です（シンボリックリンク経由を含め）、そのディレクトリの外に出るパスは拒否されます。
• image/* のレスポンスのみ保存されます。最大50 MiB、タイムアウトは30秒です。リダイレクト先は許可されたホストに限られます。
• 既存のファイルが上書きされることはありません。
• Unsplash からのダウンロードには UNSPLASH_API_KEY が必要です。API ガイドラインの要件に従い、このツールは Unsplash のダウンロードエンドポイントを呼び出します。

エラー

失敗した場合は isError: true が返されます。一部のプロバイダーが失敗しても他のプロバイダーが成功した場合、search_images はプロバイダーごとの errors リストも返します。プロバイダーへのリクエストは10秒でタイムアウトし、ネットワークエラー、429、502/503/504 の場合は再試行されます。

クレジット表記とライセンス

画像には各プロバイダーのライセンスが適用されます。プロバイダーが求める場合は撮影者のクレジットを記載し（そのための author と authorUrl が返されます）、利用条件を確認してください：Pexels、Unsplash、Pixabay。

開発

npm ci
npm run lint && npm run format:check && npm run typecheck && npm test

CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md を参照してください（脆弱性は公開イシューではなく、非公開で報告してください）。

ライセンス

MIT