Which integrations are available for this server?

Searches and downloads free stock photos from Pexels with support for orientation and dominant-color filters. Searches and downloads free stock photos from Pixabay, ensuring self-hosting compliance. Searches and downloads free stock photos from Unsplash with automatic download tracking for API compliance.

How do I use imagebank-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@imagebank-mcp Search for a landscape photo of a mountain lake and download it as hero-mountain.webp" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

imagebank-mcp

by romulorasec

Overview Schema Related Servers Score Discussions

TypeScript

Local

imagebank-mcp

MCP server that lets AI coding agents (Claude Code, Codex, Cursor, Antigravity, Cline, Windsurf and any MCP-compatible client) search free stock photos on Pexels, Unsplash and Pixabay, download them, and convert them to WebP directly into your project — no placeholders, no hotlinking, no manual image hunting.

Built for web developers: the agent asks for "a hero photo of artisan bread", gets real results, saves an optimized public/images/hero-artisan-bread.webp, and writes the <Image> tag pointing to it. Done.

Tools

Tool	What it does
`search_images`	Searches one or all configured providers in parallel. Returns preview URL, download URL, dimensions, author and attribution link. Supports orientation and dominant-color filters.
`download_image`	Downloads a result, converts to WebP (quality and max-width configurable), saves inside the project, returns the path ready for `<Image src>`. Automatically fires the Unsplash download-tracking endpoint when required.
`optimize_local_image`	Same pipeline for local files. Use it when the client replaces stock photos with their own, so performance stays consistent.

Related MCP server: unsplash-mcp

Requirements

Node.js >= 18.17
At least one API key (all free):
- Pexels: https://www.pexels.com/api/
- Unsplash: https://unsplash.com/developers (use the Access Key)
- Pixabay: https://pixabay.com/api/docs/

First install may take a bit longer: sharp (image processing) downloads a prebuilt native binary for your platform. This is normal.

Installation

The recommended way is npx — nothing to install manually, each client just points at the package:

"command": "npx",
"args": ["-y", "imagebank-mcp"]

API keys go in the env block of each client config. Never commit keys to a repository. Only the keys you set are used; missing providers are simply skipped.

Claude Code

Per project (.mcp.json at the project root) or global (~/.claude.json):

{
  "mcpServers": {
    "image-banks": {
      "command": "npx",
      "args": ["-y", "imagebank-mcp"],
      "env": {
        "PEXELS_API_KEY": "your_key",
        "UNSPLASH_ACCESS_KEY": "your_key",
        "PIXABAY_API_KEY": "your_key"
      }
    }
  }
}

Or via CLI:

claude mcp add image-banks -e PEXELS_API_KEY=your_key -e UNSPLASH_ACCESS_KEY=your_key -e PIXABAY_API_KEY=your_key -- npx -y imagebank-mcp

Cursor

.cursor/mcp.json in the project (or ~/.cursor/mcp.json global). Same JSON shape as Claude Code above.

OpenAI Codex CLI

~/.codex/config.toml:

[mcp_servers.image-banks]
command = "npx"
args = ["-y", "imagebank-mcp"]

[mcp_servers.image-banks.env]
PEXELS_API_KEY = "your_key"
UNSPLASH_ACCESS_KEY = "your_key"
PIXABAY_API_KEY = "your_key"

Antigravity

Agent settings → MCP servers → add server. Uses the same JSON structure as Claude Code (mcpServers block with command, args, env).

Cline / Roo Code (VSCode)

MCP settings file (cline_mcp_settings.json): same JSON shape as Claude Code.

Windsurf

~/.codeium/windsurf/mcp_config.json: same JSON shape as Claude Code.

Gemini CLI

~/.gemini/settings.json, inside mcpServers: same JSON shape as Claude Code.

Config file locations change between client versions. If a path above doesn't match your install, check the client's MCP docs — the server block itself (command/args/env) is identical everywhere.

Usage

You rarely call the tools explicitly. In normal use the agent decides on its own:

"Build the hero section for the bakery with a photo of fresh sourdough coming out of the oven."

The agent will call search_images (query in English, orientation: landscape), pick a result, call download_image, and write the component using the returned local path.

Explicit prompts also work:

Search 6 landscape photos of "modern dental clinic reception" on unsplash,
download the best one as hero-clinic-reception at quality 85.

Recommended agent guidance

Add to your CLAUDE.md / rules file for best behavior:

Images: when the design needs photos and the client has not provided any,
use the image-banks MCP (search_images then download_image). Search in
English. Never hotlink stock URLs; always download to public/images.
Prefer client-provided photos when they exist (optimize them with
optimize_local_image). Avoid stock photos with prominent faces for paid ads.

Image licensing (read this once)

All three providers allow free commercial use without attribution on the final website. Still:

Unsplash API rule: when a photo is actually used, the download endpoint must be pinged. download_image does this automatically when you pass trackDownloadUrl.
Pixabay: permanent hotlinking is prohibited — you must self-host. This server downloads by design, so you're compliant by default.
Model releases: none of the platforms verify consent of people appearing in photos. Avoid images with recognizable faces in paid advertising; fine for regular site sections.
Attribution is not required but is appreciated — the attributionUrl and author fields are always returned if you want to credit.

This is not legal advice; check each provider's license for your specific case.

Security

SSRF protection: download_image only accepts https URLs on pexels.com, unsplash.com, pixabay.com and subdomains. Internal IPs, cloud metadata endpoints and arbitrary hosts are rejected.
Path traversal protection: filenames are sanitized to kebab-case; output and input paths must resolve inside the working directory.
Size and type limits: downloads capped at 25 MB; content-type validated; sharp pixel-bomb limit set.
Keys: read from env only, never logged, never echoed in tool output.
Runs locally over stdio. Nothing is hosted; no data leaves your machine except the API calls to the providers you configured.

Local development

git clone https://github.com/romuloquintanilha/imagebank-mcp
cd imagebank-mcp
npm install
npm run build
npm test          # unit + real MCP protocol + sharp pipeline tests
npm run inspector # interactive UI to call tools manually

For the inspector, export your keys first (export PEXELS_API_KEY=...).

License

MIT — see LICENSE. The code is MIT; the images you download are governed by each provider's own license.

Available Tools

3 tools

download_imageA

Download an image found via search_images, convert it to WebP, optionally resize it, and save it inside the project (default public/images). Returns the relative path ready for . Always pass trackDownloadUrl when the result came from Unsplash. Only URLs from pexels.com, unsplash.com and pixabay.com are accepted.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	downloadUrl field from a search_images result.
`quality`	No	WebP quality. 80 is the sweet spot for web.
`filename`	Yes	Descriptive file name without extension, kebab-case (e.g. 'hero-artisan-bread'). Extension .webp is added automatically.
`maxWidth`	No	Resize down to this width if the original is wider (aspect ratio preserved, never upscaled).
`outputDir`	No	Relative directory inside the project to save the file.	public/images
`overwrite`	No	Overwrite the file if it already exists.
`trackDownloadUrl`	No	trackDownloadUrl from an Unsplash result. Required by Unsplash API guidelines when the photo is used.

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description covers key behaviors: conversion to WebP, optional resizing, default output directory, overwrite parameter, and the Unsplash requirement. It does not explicitly mention side effects like network requests or file system writes, but these are implied. A higher score would require explicit mention of non-destructiveness or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured. It opens with the main action and result, then adds important constraints and guidelines. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the return value (relative path for <Image src>). It covers all major aspects: source URLs, conversion, resizing, quality, naming, and overwrite behavior. The tool's purpose and usage are thoroughly described for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema: clarifies the filename should be kebab-case, maxWidth resizes down only, outputDir default is public/images, and trackDownloadUrl is required for Unsplash. This provides useful context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads an image, converts it to WebP, optionally resizes it, saves it in the project, and returns a relative path. It distinguishes from siblings by specifying it works with URLs from search_images and mentions the accepted sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use the tool: after search_images, and only for URLs from pexels.com, unsplash.com, and pixabay.com. Also specifies that trackDownloadUrl must be passed for Unsplash results, providing clear prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

optimize_local_imageA

Convert a local image file (e.g. a client-provided photo) to WebP with the same pipeline used by download_image: EXIF rotation, max-width resize, quality control. Use it when replacing stock photos with the client's real photos so performance stays consistent. Input must be a file inside the project directory.

ParametersJSON Schema

Name	Required	Description	Default
`quality`	No
`filename`	No	Output name without extension, kebab-case. Defaults to the source file name.
`maxWidth`	No
`inputPath`	Yes	Relative path to the source image inside the project.
`outputDir`	No	Relative directory inside the project to save the file.	public/images
`overwrite`	No

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses the conversion pipeline (EXIF rotation, resize, quality), which adds behavioral context. However, it does not mention potential side effects like overwrite behavior (default false), file size limits, or error handling, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each essential: defines function, gives usage context, states constraint. No fluff. Information is front-loaded and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of output schema and annotations, the description covers purpose, usage, and input constraint. However, it omits details about return value (e.g., success/path), error conditions, and behavior of parameters like overwrite. This is adequate but leaves the agent needing to infer some behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (3 of 6 parameters have descriptions). The description adds context about the pipeline (quality, max-width) but does not elaborate on individual parameter semantics beyond what the schema already provides. Baseline 3 is appropriate; it doesn't significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it converts a local image to WebP using a specific pipeline (EXIF rotation, max-width resize, quality control). It distinguishes from siblings by mentioning the same pipeline as download_image and a specific use case (replacing stock photos).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance ('Use it when replacing stock photos...') and a key constraint ('Input must be a file inside the project directory'). This helps the agent decide context, though it doesn't explicitly mention when not to use it or contrast with search_images.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_imagesA

Search free stock photos on Pexels, Unsplash and Pixabay. Use when the project needs a real photo and the client has NOT provided their own images. Prefer client-provided photos when they exist. Queries in English return better results. Returns preview URL, download URL, dimensions, author and attribution link per image. To place an image in the project, pass its downloadUrl (and trackDownloadUrl if present) to the download_image tool instead of hotlinking the URL.

ParametersJSON Schema

Name	Required	Description	Default
`color`	No	Optional dominant color filter to match brand palette (e.g. 'blue', 'green', 'orange'). Support varies by provider.
`query`	Yes	Search terms, in English (e.g. 'artisan bread rustic bakery')
`perPage`	No	Results per provider.
`provider`	No	Which provider to search. 'all' queries every configured one.	all
`orientation`	No	landscape for heroes/banners, portrait for cards/mobile.	any

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool searches multiple providers, returns specific fields (preview URL, download URL, dimensions, author, attribution link), and warns against hotlinking. However, it does not mention rate limits, authentication requirements, or any side effects, which would make it fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph but packs essential information without redundancy. It is concise and front-loaded with the main purpose, though it could be slightly more structured (e.g., bullet points for return fields).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must cover return values, which it does by listing preview URL, download URL, dimensions, author, and attribution link. It also explains the workflow with the sibling tool. For a search tool, this is fairly complete, though it lacks details on pagination or error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to use the download URL (pass to download_image) and mentions that English queries yield better results and that color filter support varies by provider, going beyond the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches free stock photos on Pexels, Unsplash, and Pixabay. It distinguishes from the sibling tool download_image by specifying that search results should be passed to that tool for placing images. The purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('when the project needs a real photo and the client has NOT provided their own images') and when not to ('Prefer client-provided photos when they exist'). It also gives a tip about English queries and directs the agent to use download_image for placing images, which is excellent guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

3 tool updatesv1.0.0Jul 8, 2026
- First observeddownload_image
- First observedoptimize_local_image
- First observedsearch_images

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a distinct purpose: searching stock photos, downloading with conversion, and optimizing local images. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (search_images, download_image, optimize_local_image), making them predictable.

Tool Count5/5

With 3 tools, the server is well-scoped for basic image bank operations: search, download, and optimize. The count is appropriate and not excessive.

Completeness4/5

The core workflow (search, download, optimize) is covered. Minor gaps exist, such as no tool for listing or deleting downloaded images, but these do not hinder the primary use case.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-qwen-imageOAuth
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
mcp-flux-proOAuth
io.github.AceDataCloud
MCP server for Flux AI image generation
Image & Video Processing Multimedia Processing
23
mcp-wanOAuth
io.github.AceDataCloud
MCP server for Wan AI video generation
AI & Machine Learning Image & Video Processing
21

Related MCP Servers

stock-images-mcp
Search Image & Video Processing App Automation
jeanpfs
A
license
B
quality
D
maintenance
MCP server to search and download stock images from Pexels, Unsplash, and Pixabay
Updated 7 months ago (2026-02-11 12:29 UTC)
2
410
3
MIT
unsplash-mcp
Art & Culture Search
cevatkerim
A
license
A
quality
D
maintenance
An MCP server for searching and retrieving photos from Unsplash with proper attribution, designed for LLMs building content pages.
Updated 8 months ago (2026-01-10 19:49 UTC)
3
24
MIT
pexels-mcp-server
Image & Video Processing Search
VictorNain26
A
license
A
quality
C
maintenance
An MCP server that enables AI agents to search, retrieve, and curate free stock photos and videos from Pexels, with tools, resources, and prompts for easy integration.
Updated a month ago (2026-08-03 04:17 UTC)
8
MIT
MCP Image Resolver
Search Image & Video Processing
ahmaddioxide
A
license
A
quality
F
maintenance
An MCP server that enables AI assistants to search for royalty-free images from Pexels and Unsplash using natural language, returning structured results with metadata.
Updated 6 months ago (2026-03-05 09:44 UTC)
5
59
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/romulorasec/imagebank-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server