Stock Image MCP

stock-image-mcp

Claude Code（またはMCP互換のエージェント）がツール呼び出しでストック画像を検索、ダウンロードできるMCP サーバーです。SEOブログ記事やその他のコンテンツの執筆中に画像を探すのに便利です。

プロバイダー

プロバイダー	API の種類	キーが必要	デフォルトのレート制限
Unsplash	公式	はい	デモ：50/時、本番：5000/時
Pexels	公式	はい	200/時
Pixabay	公式	はい	100 リクエスト/60 秒
Freepik	公式	はい	設定可能（プランによる）
StockVault	公式	はい	設定可能（非公開、保守的なデフォルト値）
Burst (Shopify)	非公式スクレイピング	いいえ	自主設定、控えめなデフォルト

Burstには公開APIがありません。ベストエフォートのHTMLスクレイパーとして含まれており、コード内でサポート対象外であることが明記されています。失敗してもそのエラーは捕捉され、search_all_images が中断するのではなく、空の結果として報告されます。

インストール

各ユーザーがサーバーをローカルで実行し、自分のプロバイダーAPIキーを設定します。共有ホスティングや一元管理されたキーはありません。

Claude Codeを使用する場合：

claude mcp add stock-image-mcp \
  -e UNSPLASH_ACCESS_KEY=... \
  -e UNSPLASH_TIER=demo \
  -e PEXELS_API_KEY=... \
  -e PIXABAY_API_KEY=... \
  -e FREEPIK_API_KEY=... \
  -e FREEPIK_REQUESTS_PER_MINUTE=60 \
  -e STOCKVAULT_API_KEY=... \
  -e STOCKVAULT_REQUESTS_PER_HOUR=60 \
  -e BURST_REQUESTS_PER_MINUTE=10 \
  -e DEFAULT_PROVIDER=pexels \
  -e DOWNLOAD_DIR=./downloads \
  -- uvx stock-image-mcp

OpenAI Codex CLIを使用する場合：

codex mcp add stock-image-mcp \
  --env UNSPLASH_ACCESS_KEY=... \
  --env UNSPLASH_TIER=demo \
  --env PEXELS_API_KEY=... \
  --env PIXABAY_API_KEY=... \
  --env FREEPIK_API_KEY=... \
  --env FREEPIK_REQUESTS_PER_MINUTE=60 \
  --env STOCKVAULT_API_KEY=... \
  --env STOCKVAULT_REQUESTS_PER_HOUR=60 \
  --env BURST_REQUESTS_PER_MINUTE=10 \
  --env DEFAULT_PROVIDER=pexels \
  --env DOWNLOAD_DIR=./downloads \
  -- uvx stock-image-mcp

Gemini CLIを使用する場合：

gemini mcp add stock-image-mcp \
  -e UNSPLASH_ACCESS_KEY=... \
  -e UNSPLASH_TIER=demo \
  -e PEXELS_API_KEY=... \
  -e PIXABAY_API_KEY=... \
  -e FREEPIK_API_KEY=... \
  -e FREEPIK_REQUESTS_PER_MINUTE=60 \
  -e STOCKVAULT_API_KEY=... \
  -e STOCKVAULT_REQUESTS_PER_HOUR=60 \
  -e BURST_REQUESTS_PER_MINUTE=10 \
  -e DEFAULT_PROVIDER=pexels \
  -e DOWNLOAD_DIR=./downloads \
  -- uvx stock-image-mcp

または、uvxを使ってMCP設定に手動で追加します（クローンやインストールの手順は不要です。uvxは初回実行時にPyPIからパッケージを取得します）。

{
  "mcpServers": {
    "stock-image-mcp": {
      "command": "uvx",
      "args": ["stock-image-mcp"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "...",
        "UNSPLASH_TIER": "demo",
        "PEXELS_API_KEY": "...",
        "PIXABAY_API_KEY": "...",
        "FREEPIK_API_KEY": "...",
        "FREEPIK_REQUESTS_PER_MINUTE": "60",
        "STOCKVAULT_API_KEY": "...",
        "STOCKVAULT_REQUESTS_PER_HOUR": "60",
        "BURST_REQUESTS_PER_MINUTE": "10",
        "DEFAULT_PROVIDER": "pexels",
        "DOWNLOAD_DIR": "./downloads"
      }
    }
  }
}

実際のシークレットは UNSPLASH_ACCESS_KEY、PEXELS_API_KEY、PIXABAY_API_KEY、FREEPIK_API_KEY、STOCKVAULT_API_KEY のみです。有効にするプロバイダーのキーだけを設定し、それ以外は削除してください。省略したプロバイダーキーは search_all_images で単にスキップされ、search_stock_images から直接クエリすると拒否されます。残りの変数は任意の調整用設定で、上記のデフォルト値が示されています。全一覧は .env.example を参照してください。

ツール

• search_stock_images(query, provider="default", orientation=None, per_page=10, page=1)
• search_all_images(query, orientation=None, per_page=5) — 設定済みのすべてのプロバイダーに同時に検索を実行します
• get_best_image(query, provider="default")
• download_image(url, dest_path, provider=None) — 画像をローカルに保存します。画像が以前の検索結果に含まれていた場合は、帰属表示テキストを返します
• get_attribution(provider, image_id)
• get_rate_limit_status(provider=None)

使い方

これらのツールを直接呼び出す必要はありません。エージェントに話しかけるだけで、依頼内容と上記のツールの説明に基づいて、エージェントが使うツールを判断します。知っておくと便利な点をいくつか紹介します。

• 普通の英語で依頼してください。「ブログ記事用に山の風景写真を3枚探して」と頼むだけで、search_all_images が呼び出されます（プロバイダーを指定した場合は、search_stock_images が呼び出されます）。「最初のUnsplashの検索結果を ./images/hero.jpg にダウンロードして」と頼むと、download_image が呼び出されます。「今の時間、Pexelsのリクエストはあと何回できますか？」と尋ねると、get_rate_limit_status が呼び出されます。
• search_stock_images では、特定のプロバイダー（または "default"）を指定する必要があります。search_all_images は、キーを設定したすべてのプロバイダーに問い合わせて、結果をまとめます。使用するプロバイダーを指定したい場合は、「Pexelsだけを検索して」のように依頼してください。
• 複数のプロバイダー（特にUnsplashとPexels）では、画像を公開して使用する場合、帰属表示が必要です。download_image は該当する場合、画像ファイルと一緒に帰属表示のテキストを返します。画像の使用先にそのテキストを貼り付けるのはご自身の責任です。サーバーは代わりに対応しません。
• 会話を介さずに手動でツールを呼び出したい場合は、下記の「開発」にある「MCP Inspector」のセクションをご覧ください。

ローカルでの開発

公開済みパッケージではなく、クローンから作業する場合：

uv sync
cp .env.example .env   # fill in the API keys for providers you want enabled
uv run stock-image-mcp

uvx の代わりに、ローカルのチェックアウトを参照するようにClaudeの設定を変更してください：

{
  "mcpServers": {
    "stock-image-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/stock-image-mcp",
        "run",
        "stock-image-mcp"
      ],
      "env": {
        "UNSPLASH_ACCESS_KEY": "...",
        "UNSPLASH_TIER": "demo",
        "PEXELS_API_KEY": "...",
        "PIXABAY_API_KEY": "...",
        "FREEPIK_API_KEY": "...",
        "FREEPIK_REQUESTS_PER_MINUTE": "60",
        "STOCKVAULT_API_KEY": "...",
        "STOCKVAULT_REQUESTS_PER_HOUR": "60",
        "BURST_REQUESTS_PER_MINUTE": "10",
        "DEFAULT_PROVIDER": "pexels",
        "DOWNLOAD_DIR": "./downloads"
      }
    }
  }
}

開発

uv run pytest              # test suite (mocked HTTP, no live keys needed)
uv run ruff check .         # lint
uv run ruff format .        # format
uv run mypy src             # type check

実際のプロバイダーで動作を試すには、MCP Inspectorを使用してください：

npx @modelcontextprotocol/inspector uv run stock-image-mcp