Image Search

CI CodeQL Python 3.10+ MCP Python SDK 2.x License: MIT

Image Search MCP is a Model Context Protocol server for searching Unsplash, Pexels, and Pixabay from one MCP client. Search one provider or all configured providers concurrently, return normalized image metadata, inspect image details, and download results.

Use it as an Unsplash MCP server, Pexels MCP server, Pixabay MCP server, or one unified MCP image search tool.

Features

• Search Unsplash, Pexels, and Pixabay through one MCP server
• Query multiple configured providers concurrently
• Filter searches to specific providers
• Normalize results into one consistent image schema
• Fetch detailed metadata for individual images
• Download images or return base64 image data
• Run locally over MCP or deploy with Streamable HTTP
• Fail clearly when a requested provider is invalid or not configured

Getting Started

Have an AI agent install it

Give your coding agent or AI assistant this install skill and let it configure the MCP for you:

skills/install-mcp/SKILL.md

1. Clone and install

git clone https://github.com/Serbyte-Development/image-search-mcp.git
cd image-search-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Get provider API keys

Configure one or more of these environment variables:

PEXELS_API_KEY
UNSPLASH_ACCESS_KEY
PIXABAY_API_KEY

API keys are available from:

• Pexels: https://www.pexels.com/api/
• Unsplash: https://unsplash.com/developers
• Pixabay: https://pixabay.com/api/docs/

You only need keys for the providers you want to use.

3. Add the MCP server to your client

{
  "mcpServers": {
    "image-search": {
      "command": "/absolute/path/to/image-search-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/image-search-mcp/image_search_mcp.py"
      ],
      "env": {
        "PEXELS_API_KEY": "your_pexels_key",
        "UNSPLASH_ACCESS_KEY": "your_unsplash_key",
        "PIXABAY_API_KEY": "your_pixabay_key"
      }
    }
  }
}

Restart your MCP client after saving the configuration.

MCP Tools

search_stock_images

Search one or more configured providers.

Parameters:

• query - search query
• providers - optional list containing pexels, unsplash, and/or pixabay
• per_page - results per provider, clamped to 1-50
• page - page number
• sort_by - relevant or newest
• include_attribution - include provider attribution links when available

Example:

{
  "query": "modern office interior",
  "providers": ["unsplash", "pexels"],
  "per_page": 10
}

get_image_details

Fetch detailed metadata for a provider-prefixed image ID such as pexels_123456.

download_image

Download an image by ID. Supported size values are thumbnail, small, medium, large, and original.

If output_path is omitted, the tool returns base64 image data instead of writing a file.

Result Format

Search results are normalized across providers and include fields such as:

{
  "id": "pexels_123456",
  "title": "Example image",
  "url": "https://...",
  "thumbnail": "https://...",
  "width": 1920,
  "height": 1080,
  "photographer": "Photographer Name",
  "source": "Pexels",
  "license": "Provider license",
  "tags": []
}

Run from the CLI

Install the local command:

pip install -e .

Then run:

image-search-mcp

Deploy with Streamable HTTP

app.py exposes a stateless Streamable HTTP MCP endpoint suitable for Vercel.

Set your provider API keys in the deployment environment, deploy the repository, then connect MCP clients to:

https://your-project.vercel.app/mcp

The example deployment does not add authentication. If you expose an MCP endpoint publicly, add appropriate access controls or expect requests to consume your provider API quotas.

Optional transport security settings:

IMAGE_SEARCH_MCP_ALLOWED_HOSTS
IMAGE_SEARCH_MCP_ALLOWED_ORIGINS

Both accept comma-separated values.

Development

Install development dependencies:

pip install -r requirements-dev.txt

Run lint, type checks, and unit tests:

make check PYTHON=.venv/bin/python

The repository also runs CI and CodeQL on pushes and pull requests to main.

Image Licensing

This project is MIT licensed, but images returned by the providers are governed by each provider's own current license and API terms. Review the applicable provider terms before using downloaded content in production.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for vulnerability reporting.

License

MIT - see LICENSE.

Developed & maintained by Serbyte Development.