# Stock Images MCP [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/jeanpfs/stock-images-mcp  
**GitHub Stars:** 4  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/stock-images-mcp

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

## Tools
Capabilities this server exposes over MCP:

- **provider** — `"pexels"`, `"unsplash"`, `"pixabay"`, or `"all"` (default: `"all"`)
- **count** — results per provider (default 5, max 20)
- **orientation** — `"landscape"`, `"portrait"`, or `"square"`
- **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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "stock-images-mcp": {
    "command": "npx",
    "args": ["-y","stock-images-mcp"],
    "env": {
      "PEXELS_API_KEY": "",
      "UNSPLASH_API_KEY": "",
      "PIXABAY_API_KEY": "",
      "STOCK_IMAGES_DOWNLOAD_DIR": ""
    }
  }
}
```

**Requires environment variables:** `PEXELS_API_KEY`, `UNSPLASH_API_KEY`, `PIXABAY_API_KEY`, `STOCK_IMAGES_DOWNLOAD_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Stock Images MCP MCP server does

Stock Images MCP provides two MCP tools for finding and saving stock images. `search_images` searches Pexels, Unsplash, Pixabay, or all configured providers. Each result includes identifying and attribution information such as the provider, image URL, thumbnail, description, author, author URL, dimensions, and a `downloadUrl` intended for the download step.

`download_image` saves an image to the configured local download directory. An agent can provide a filename and an optional subfolder. Filenames are restricted to letters, numbers, underscores, hyphens, and periods. If no extension is supplied, the server derives one from the response content type; if the filename is omitted, it generates one automatically.

The Stock Images MCP MCP server is suited to agents that need to locate visual assets without switching between provider APIs manually. It can support tasks such as gathering candidate images, selecting results by orientation, and placing approved assets into a local project directory.

## How it works

Search requires a query. The provider can be selected individually or set to `all`, which is the default. Results per provider default to five and can be increased to 20. The optional orientation filter accepts `landscape`, `portrait`, or `square`.

A typical workflow is to call `search_images`, inspect the returned metadata, and pass a result's `downloadUrl` to `download_image`. Search requests time out after 10 seconds and retry network failures, rate-limit responses, and common gateway errors. If one provider fails while others return results, the response includes provider-specific errors rather than hiding the partial results.

Downloads accept HTTPS image URLs on the supported provider hosts. Only responses with an `image/*` content type are saved, the maximum file size is 50 MiB, and requests time out after 30 seconds. Redirects are followed only when they remain within allowed hosts. Existing files are not overwritten.

## Setup and configuration

The Stock Images MCP MCP server requires at least one of `PEXELS_API_KEY`, `UNSPLASH_API_KEY`, or `PIXABAY_API_KEY`. Set `STOCK_IMAGES_DOWNLOAD_DIR` to change the destination; otherwise files go to `./downloads`.

The documented package setup uses Node.js 22 or newer and runs through `npx -y stock-images-mcp`. Configuration examples are provided for Claude Code, Cursor, and Claude Desktop. Docker is also supported, including a volume mount for the downloads directory. From source, clone the repository, run `npm ci`, build with `npm run build`, and start `node dist/index.js`.

## Tools and capabilities

- Search one provider or all configured providers.
- Limit result count per provider to a maximum of 20.
- Filter search results by image orientation.
- Download images into the base directory or a safe subfolder.
- Return author and author URL fields for attribution workflows.
- Report tool failures with `isError: true`.

## Limitations and notes

Provider API keys are supplied by the user and must be obtained from the respective provider. Unsplash downloads require `UNSPLASH_API_KEY` because the server uses Unsplash's download endpoint as required by its API guidelines.

The Stock Images MCP MCP server does not change image licensing. Images remain subject to the license of their source provider, and users should review the applicable terms and credit photographers when required. Download paths that escape the configured directory, including paths involving symlinks, are rejected. The server also does not overwrite existing files.

_Full upstream README: https://allmcps.com/mcp/stock-images-mcp/readme_