Stock Image MCP

stock-image-mcp

An MCP server that lets Claude Code (or any MCP-compatible agent) search and download stock images by tool call — useful for sourcing images while writing SEO blog posts or other content.

Providers

Burst has no public API. It's included as a best-effort HTML scraper, clearly marked unsupported in code — any failure there is caught and reported as an empty result rather than breaking search_all_images.

Install

Each user runs the server locally and supplies their own provider API keys — there's no shared hosting or centrally-held keys.

With 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

With 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

With 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

Or add it to your MCP config manually with uvx (no clone or install step required — uvx fetches the package from PyPI on first run):

{

"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" } } } }

Only UNSPLASH_ACCESS_KEY, PEXELS_API_KEY, PIXABAY_API_KEY, FREEPIK_API_KEY, and STOCKVAULT_API_KEY are actual secrets — set only the ones for providers you want enabled and drop the rest; any provider key you omit is simply skipped by search_all_images and rejected if queried directly via search_stock_images. The remaining variables are optional tuning knobs shown above with their defaults — see .env.example for the full list.

Tools

• search_stock_images(query, provider="default", orientation=None, per_page=10, page=1)
• search_all_images(query, orientation=None, per_page=5) — fans out to every configured provider concurrently
• get_best_image(query, provider="default")
• download_image(url, dest_path, provider=None) — saves locally, returns attribution text if the image came from a prior search
• get_attribution(provider, image_id)
• get_rate_limit_status(provider=None)

Usage

You don't call these tools directly — you just talk to your agent, and it decides when to reach for one based on what you asked and the tool descriptions above. A few things worth knowing:

• Just ask in plain English. "Find me 3 landscape photos of mountains for a blog post" is enough to trigger search_all_images (or search_stock_images if you name a provider). "Download that first Unsplash result to ./images/hero.jpg" triggers download_image. "How many Pexels requests do I have left this hour?" triggers get_rate_limit_status.
• search_stock_images needs a specific provider (or "default"); search_all_images just queries everything you've configured keys for and merges the results. Say "search Pexels only" or similar if you care which one gets used.
• Several providers (Unsplash and Pexels in particular) require attribution if you actually use the image somewhere public. download_image returns the attribution text alongside the file when it applies — it's on you to paste it wherever the image ends up, the server won't do that part for you.
• Want to call tools by hand instead of through a conversation? See the MCP Inspector section under Development below.

Developing locally

Working from a clone instead of the published package:

uv sync

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

Point your Claude config at the local checkout instead of uvx:

{

"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" } } } }

Development

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

To try it against real providers, use the MCP Inspector:

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