pexels-mcp

A full-coverage Model Context Protocol (MCP) server for the Pexels API. Gives AI assistants (Claude, Cursor, etc.) direct access to millions of free stock photos and videos.

Features

• 10 MCP tools covering all Pexels API endpoints — photos, videos, and collections
• Formatted responses — readable text with direct URLs, not raw JSON dumps
• Rate limit tracking — check your quota anytime via get_api_stats
• Full filter support — orientation, size, color (named or hex), locale (28 languages)
• Zero config — just set your API key and run

Prerequisites

1. Node.js 18+
2. A free Pexels API key — get one at pexels.com/api (free, instant approval)

Setup

Claude Code

Add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "pexels-mcp"],
      "env": {
        "PEXELS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Then run /mcp in Claude Code to verify the server is connected.

Cursor IDE

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level):

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "pexels-mcp"],
      "env": {
        "PEXELS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP Clients

{
  "command": "npx",
  "args": ["-y", "pexels-mcp"],
  "env": {
    "PEXELS_API_KEY": "your-api-key-here"
  }
}

Run Locally (after npm install -g pexels-mcp)

PEXELS_API_KEY=your_key pexels-mcp
# or
pexels-mcp --api-key your_key

Available Tools

Photos

| Tool | Description | |------|-------------| | search_photos | Search photos by keyword with filters (orientation, size, color, locale) | | get_curated_photos | Browse Pexels editorial picks (updated hourly) | | get_photo | Get full details for a photo by ID |

Videos

| Tool | Description | |------|-------------| | search_videos | Search videos by keyword with filters (orientation, size, duration, resolution, locale) | | get_popular_videos | Browse currently trending videos | | get_video | Get full details for a video by ID |

Collections

| Tool | Description | |------|-------------| | get_featured_collections | Browse Pexels featured/editorial collections | | get_my_collections | List collections owned by your API key's account | | get_collection_media | Get photos/videos inside a specific collection |

Utility

| Tool | Description | |------|-------------| | get_api_stats | Check remaining API quota and reset time (no new request made) |

Tool Parameters

search_photos

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | ✓ | Search keywords | | orientation | landscape | portrait | square | | Filter by orientation | | size | large | medium | small | | Minimum size (24MP / 12MP / 4MP) | | color | string | | Named color or #rrggbb hex | | locale | string | | One of 28 locales (e.g. en-US, fr-FR) | | page | number | | Page number (default: 1) | | per_page | number | | Results per page, max 80 (default: 15) |

search_videos

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | ✓ | Search keywords | | orientation | landscape | portrait | square | | Filter by orientation | | size | large | medium | small | | Min size (4K / Full HD / HD) | | locale | string | | One of 28 locales | | page / per_page | number | | Pagination | | min_duration | number | | Minimum duration in seconds | | max_duration | number | | Maximum duration in seconds | | min_width | number | | Minimum width in pixels | | min_height | number | | Minimum height in pixels |

get_collection_media

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | ✓ | Collection ID from featured/my collections | | type | photos | videos | | Filter media type | | page / per_page | number | | Pagination |

Rate Limits

Pexels free tier: 200 requests/hour and 20,000 requests/month.

Use get_api_stats after any API call to check your current usage. If you need higher limits, request them at pexels.com/api.

Supported Locales

en-US pt-BR es-ES ca-ES de-DE it-IT fr-FR sv-SE id-ID pl-PL ja-JP zh-TW zh-CN ko-KR th-TH nl-NL hu-HU vi-VN cs-CZ da-DK fi-FI uk-UA el-GR ro-RO nb-NO sk-SK tr-TR ru-RU

License

MIT