MCP Server Pexels

mcp-server-pexels

An MCP server for Pexels stock photo and video search. Optimized for LLMs.

[]()

Pexels provides free stock photos and videos.

Features

• Photo Search — Search photos with filters (query, orientation, size, color, locale)
• Video Search — Search videos, auto-selects HD .mp4 closest to 1920x1080
• Get Details — Retrieve full metadata for a photo/video by ID
• Intelligent Caching — 10 min TTL for searches, 60 min for ID lookups
• Error Handling — Graceful failures with helpful messages (per MCP best practices)
• Attribution — Mandatory photographer credits in every result

For LLM agents: See docs/agents/AGENTS.md for agent-optimized documentation — tool semantics, caching behaviour, response structure, and attribution requirements.

Prerequisites

• Node.js v20+
• Pexels API key (free at pexels.com/api)

Quick Start (2 minutes)

1. Get an API Key

Sign up at pexels.com/api — free, no credit card.

2. Build the Server

npm install && npm run build

3. Add to Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows), add:

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-pexels/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_PEXELS_API_KEY"
      }
    }
  }
}

Windows note: Use node.exe full path or add Node to PATH. Forward slashes in paths work on Windows.

4. Restart Claude Desktop

The server is now available as pexels_search_photos, pexels_search_videos, and pexels_get_details.

Configuration

Add to your .mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Environment

Set PEXELS_API_KEY in your environment. For local dev, create a .env file:

PEXELS_API_KEY=your_pexels_api_key

Development

npm run dev       # watch mode
npm run inspector # MCP Inspector
npm test          # build + run all tests (125+)
npm run lint      # check code style with Biome
npm run format    # auto-format with Biome

LLM-optimized docs for agent consumers are at docs/agents/AGENTS.md.

Tools

Architecture

• src/index.ts — Entry point, MCP server setup
• src/tools/ — Tool implementations
• src/shared/ — Cache, API client, errors, types, video selector
• src/utils/ — Zod validation schemas

Engineering Decisions

Compatibility

Tested with @modelcontextprotocol/sdk v1.29+ via StdioClientTransport. The integration test suite spawns the built server and validates every tool call against the SDK's CallToolResultSchema and ContentBlockSchema.

A structured JSON block is appended as the last content element in every successful response, containing typed data (id, kind, creatorName, dimensions, URLs). Downstream clients and agent frameworks can parse this block directly instead of regex-parsing the markdown text.

Future Improvements

• Tool execution telemetry — Add structured logging for cache hits/misses, query execution time, and error rates. This supports troubleshooting AI agents in production and demonstrates observability best practices.
• Metrics endpoint — Expose counters (requests served, cache hit ratio, API quota remaining) for monitoring.
• Custom TTL configuration — Allow users to tune cache TTL via environment variables.

Community Submissions

• are welcome! 🌟

License

Unofficial community project. Not affiliated with Pexels.