Overview

The Pexels MCP Server exposes image search and download operations over a Model Context Protocol (MCP) compatible API using the Pexels image service. It acts as a lightweight bridge between language models (or other MCP-aware clients) and the Pexels API, enabling controlled, reproducible image retrieval workflows: searching by query, inspecting image metadata, and producing direct download URLs for fast transfer.

This server is useful when you need programmatic, high-quality image access inside a toolset that uses MCP tools (for example, LLM agents or orchestrators). By centralizing Pexels usage in a single, configurable service you simplify API key management, caching, and rate-limit handling while exposing a small set of safe, documented endpoints that MCP-capable models can call.

Features

Search Pexels photos by query, orientation, size, color, and more
Retrieve detailed metadata for an image (photographer, dimensions, sizes)
Generate/return fast download URLs suitable for client consumption
MCP-compatible tool manifest to integrate with LLM agents and toolchains
Optional caching and configurable download directory
Docker-ready for easy deployment and local testing

Installation / Configuration

Basic steps to get the server running locally:

Clone and install dependencies:

git clone https://github.com/garylab/pexels-mcp-server.git
cd pexels-mcp-server
npm install

Create environment variables (example .env):

PORT=3000
PEXELS_API_KEY=your_pexels_api_key_here
CACHE_TTL_SECONDS=300
DOWNLOAD_DIR=./downloads

Run the server:

npm run start
# or for development with hot reload (if available)
npm run dev

Docker

docker build -t pexels-mcp-server .
docker run -e PEXELS_API_KEY=your_key -p 3000:3000 pexels-mcp-server

Typical environment variables and purpose:

Variable	Description	Default
PORT	HTTP port to listen on	3000
PEXELS_API_KEY	Pexels API key (required)	—
CACHE_TTL_SECONDS	TTL for cached search results (seconds)	300
DOWNLOAD_DIR	Directory to store downloaded images	./downloads

Available Resources

The server exposes a small set of HTTP endpoints (common patterns—you should inspect the repository for exact paths):

GET /search
- Query parameters: q (query), page, per_page, orientation, size, color
- Returns a paginated list of images and basic metadata
GET /image/:id
- Returns detailed metadata for an image by ID
POST /download
- Body: { “id”: “<image_id>”, “size”: “original|large|medium|small” }
- Returns a signed/fast download URL or triggers a direct download to the server DOWNLOAD_DIR
GET /mcp/manifest (or similar)
- Returns an MCP tool manifest describing the tool operations — helpful for LLM integrations

Example curl: search

curl "http://localhost:3000/search?q=sunrise&per_page=10" -H "Accept: application/json"

Example curl: request download

curl -X POST "http://localhost:3000/download" \
  -H "Content-Type: application/json" \
  -d '{"id":"1234567","size":"large"}'

Example MCP tool manifest (snippet)

{
  "name": "pexels_search",
  "description": "Search and download royalty-free images via Pexels",
  "icon": "🖼️",
  "inputs": [
    { "name": "query", "type": "string" },
    { "name": "per_page", "type": "integer", "default": 10 }
  ],
  "runs": [
    { "name": "search", "url": "http://your-server/search" },
    { "name": "download", "url": "http://your-server/download" }
  ]
}

Use Cases

LLM agent image sourcing: Allow an assistant to find and fetch images to include in generated content or to provide image examples during a conversation.
Media search widget backend: Power a front-end search UI that returns curated Pexels images with consistent metadata and download links.
Automated content pipelines: Programmatically fetch image assets for batch processing (e.g., resizing, watermarking) while centralizing Pexels key usage.
Research and prototyping: Quickly prototype multimodal demos that need photo lookup and retrieval without embedding the Pexels key in many clients.
Caching/high-throughput downloads: Use the server to cache common searches and provide faster, consolidated download behavior to downstream systems.

Getting Help and Contributing

GitHub repository: https://github.com/garylab/pexels-mcp-server
Check repository issues for bug reports, feature requests, and deployment notes.
When contributing, follow the repo’s contribution guidelines and include unit tests for new behavior where applicable.

This server is intended as a practical adapter between Pexels and MCP-aware systems — it reduces duplication of integration work, centralizes API key usage, and provides a predictable surface for model-driven tooling that needs image search and download capabilities.

Pexels MCP Server — Image Search & Download