Stock Images MCP

io.github.jeanpfsv2.0.0Updated Oct 7, 2026

Search and download free stock images from Pexels, Unsplash, and Pixabay.

VerifiedSTDIODesktop onlyFiles & StorageMedia & Design

Overview

AI-generated overview

Lets an assistant search free stock photos across Pexels, Unsplash and Pixabay and save chosen images into a local folder.

What it does
Exposes two tools: search_images queries one provider or all configured providers for stock photos, returning id, provider, url, thumbnail, description, author, authorUrl, downloadUrl, width and height, with per-provider error reporting when some providers fail. download_image fetches an image from an allowed provider host into a local download directory, optionally into a subfolder with a chosen filename.
When to use it
Useful when an assistant needs real, licensed stock photography for a document, site, or design draft and should pull it directly rather than describing it. Also handy for comparing results across several image providers in one query.
Requirements
Runs locally over stdio via npx (Node.js 20+), or Docker. At least one provider API key is required: PEXELS_API_KEY, PIXABAY_API_KEY or UNSPLASH_API_KEY; Unsplash downloads specifically need UNSPLASH_API_KEY. Optional STOCK_IMAGES_DOWNLOAD_DIR sets the download folder (default ./downloads). Network access to the provider APIs is needed.
Before you install
Requires third-party API keys (PEXELS_API_KEY, PIXABAY_API_KEY, UNSPLASH_API_KEY) stored in the MCP config, so protect that file. download_image writes files to disk, though it rejects paths escaping the download directory, saves only image responses up to 50 MiB, and never overwrites existing files. Images remain under each provider's license; credit the photographer where required and review the terms.

Installation

In SourceWeft

  1. Open Stock Images MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Stock Images MCP

[CI] [npm] [license]

[Image]

An MCP (Model Context Protocol) server for searching and downloading stock images from Pexels, Unsplash, and Pixabay.

Features

  • search_images: search one or all configured providers; partial failures are reported per provider
  • download_image: download an image safely into a local folder

Setup

Get API keys (at least one required)

ProviderEnv varGet a key
PexelsPEXELS_API_KEYhttps://www.pexels.com/api/
UnsplashUNSPLASH_API_KEYhttps://unsplash.com/developers
PixabayPIXABAY_API_KEYhttps://pixabay.com/api/docs/

Optional: STOCK_IMAGES_DOWNLOAD_DIR — where download_image writes files (default ./downloads).

Claude Code / Cursor / Claude Desktop

Add to your MCP config (~/.claude/mcp.json, ~/.cursor/mcp.json, or claude_desktop_config.json):

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

Requires Node.js 20+.

Docker

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

From source

bash
git clone https://github.com/jeanpfs/stock-images-mcp.gitcd stock-images-mcpnpm ci && npm run buildPEXELS_API_KEY=xxx node dist/index.js

Tools

search_images

Search for stock images across configured providers.

Parameters:

  • query (required): search term
  • provider: "pexels", "unsplash", "pixabay", or "all" (default: "all")
  • count: results per provider (default 5, max 20)
  • orientation: "landscape", "portrait", or "square"

Each result has id, provider, url, thumbnail, description, author, authorUrl, downloadUrl, width, height. Pass downloadUrl to download_image.

download_image

Download an image into the download directory.

Parameters:

  • url (required): https image URL on pexels.com, unsplash.com or pixabay.com (use downloadUrl from search_images)
  • filename: output name — letters, digits, _, -, . only; the extension is added from the content-type if missing (auto-generated if omitted)
  • folder: subfolder inside the download directory

Behavior and limits:

  • Download directory is ./downloads, or STOCK_IMAGES_DOWNLOAD_DIR if set. Paths that escape it (including via symlinks) are rejected.
  • Only image/* responses are saved; max 50 MiB; 30 s timeout; redirects are followed only to allowed hosts.
  • Existing files are never overwritten.
  • Unsplash downloads require UNSPLASH_API_KEY: the tool calls Unsplash's download endpoint, as their API guidelines require.

Errors

Failures return isError: true. search_images also returns a per-provider errors list when some providers fail but others succeed. Provider requests time out after 10 s and are retried on network errors, 429 and 502/503/504.

Attribution and licensing

Images stay under each provider's license. Credit the photographer where the provider requires it (author and authorUrl are returned for that purpose) and review the terms: Pexels, Unsplash, Pixabay.

Development

bash
npm cinpm run lint && npm run format:check && npm run typecheck && npm test

See CONTRIBUTING.md and SECURITY.md.

License

MIT

Source: README.md at commit c1f214b

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v2.0.0LatestOct 7, 2026