MCP Server Pexels

What afshinator/mcp-server-pexels MCP server does

The afshinator/mcp-server-pexels MCP server connects MCP clients to the Pexels API for stock photo and video discovery. It exposes three tools: pexels_search_photos, pexels_search_videos, and pexels_get_details.

Photo searches accept a query and filters for orientation, size, color, and locale. Video searches return matching Pexels videos and select an HD MP4 asset closest to 1920×1080. Detail lookups retrieve metadata for a photo or video when the caller provides its ID and type.

Responses include photographer or creator attribution, which is required by Pexels terms. Successful responses also append structured JSON containing fields such as the media ID, media kind, creator name, dimensions, and URLs. Media may be exposed through MCP resource_link content blocks, with a markdown link available for clients that do not render those blocks.

How it works

The afshinator/mcp-server-pexels MCP server runs locally as a Node.js process and communicates with the MCP client over stdio. It calls the Pexels API using the configured API key, validates tool inputs with Zod schemas, and returns either structured results or an MCP error response.

Caching is enabled for API results. Search results use a 10-minute time-to-live, while lookups by media ID use a 60-minute time-to-live. Cache hits can avoid another Pexels request and help preserve the API allowance, documented by the project as 200 requests per hour.

The server warns about configuration problems during startup but defers the failure until a tool is called. This allows the process to start while still returning a structured error when the missing configuration is actually needed.

Setup and configuration

The afshinator/mcp-server-pexels MCP server requires Node.js 20 or newer and a Pexels API key. The key is available from the Pexels API website without a credit card according to the README. Build the project with npm install && npm run build, then configure an MCP client to start the generated build/index.js file with Node.

Set PEXELS_API_KEY in the server process environment. Claude Desktop configuration uses a local node command, an absolute path to build/index.js, and the API key under env. The same server settings can be placed in .mcp.json. After adding the configuration, restart Claude Desktop.

Tools and capabilities

• pexels_search_photos: searches photos by query with orientation, size, color, and locale filters.
• pexels_search_videos: searches videos and selects an HD MP4 close to 1920×1080.
• pexels_get_details: retrieves full details for a photo or video by ID and type.
• Cache handling: stores searches for 10 minutes and ID lookups for 60 minutes.
• Response handling: provides attribution, media links, and a structured JSON block for successful results.

Limitations and notes

An API key is required for tool calls, and the server depends on Pexels availability and request limits. Attribution is included in every result and should not be removed when using returned media. The project is an unofficial community implementation and is not affiliated with Pexels. Its documented client compatibility is tested with the MCP SDK through stdio; Claude Desktop is the client configuration specifically shown in the README.