Stock Images MCP

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.