What can you do with this server?

This server enables searching and retrieving free stock photos and videos from Pexels, optimized for LLM integration. * Search Photos (pexels_search_photos): Search by keyword with optional filters for orientation (landscape, portrait, square), size (large, medium, small), color (named or hex code), and locale. Returns up to 10 results with mandatory photographer attribution. * Search Videos (pexels_search_videos): Search by keyword with optional filters for orientation, size, and locale. Automatically selects HD .mp4 links closest to 1920×1080. Returns up to 10 results with attribution. * Get Details (pexels_get_details): Retrieve full metadata for a specific photo or video by ID, including dimensions, URLs, and creator credits. * Intelligent Caching: Search results are cached for 10 minutes, ID lookups for 60 minutes. A force_refresh flag bypasses the cache to fetch fresh data, helping preserve the Pexels API quota. * Attribution: Photographer credits are automatically included in every response, as required by Pexels' terms of service. * LLM Optimization: Structured JSON output and graceful error handling with informative messages for invalid requests or API issues.

Which integrations are available for this server?

Provides tools for searching stock photos and videos via the Pexels API, including filters for orientation, size, color, and locale, as well as retrieving detailed metadata by ID.

de en es ja ko ru zh

mcp-server-pexels

by afshinator

Overview Schema Related Servers Score Discussions

TypeScript

Remote

mcp-server-pexels

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

Lint MCP License mcp-server-pexels MCP server

project image

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.

Related MCP server: Pexels MCP Server

Prerequisites

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

Quick Start (2 minutes)

1. Get an API Key

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

Tool	Description
`pexels_search_photos`	Search for photos by query
`pexels_search_videos`	Search for videos
`pexels_get_details`	Get details by ID and type

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

Decision	Rationale
Cache-first architecture	Pexels API allows 200 requests/hour. Caching (10m TTL for searches, 60m for ID lookups) preserves quota, reduces latency to <5ms on cache hit, and demonstrates awareness of API costs — critical for production AI systems where agents frequently re-request the same context.
Fail-fast at call time	MCP servers are spawned as child processes — starting is not the time to fail. Server warns on startup but fails gracefully on first tool call with structured `isError: true`.
Zod validation schemas	MCP v2 SDK requires `z.object()` wrappers. Catches invalid input before it reaches the API.
resource_link for media	Remote images and videos are provided as MCP `resource_link` content blocks with proper mimeType. The markdown image link in the text block remains as a fallback for clients that do not render `resource_link`.
Pure video selection	Video selection logic isolated in `video-selector.ts` — testable independently from tool handler.
Hardcoded attribution	Required by Pexels Terms of Service. Embedded in every text response.

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.

Available Tools

3 tools

pexels_get_detailsGet Pexels DetailsA

Read-onlyIdempotent

Get detailed information about a specific photo or video by ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes
`type`	Yes
`force_refresh`	No

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds that it returns 'detailed information' but does not disclose any additional behavioral traits like rate limits or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with three parameters and no output schema, the description is minimally adequate. It fails to hint at the output format or behavior of the optional 'force_refresh' parameter, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate. It only mentions 'by ID', leaving parameters like 'type' and 'force_refresh' unexplained. While the enum for type provides some guidance, the description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'Get', resource 'detailed information about a specific photo or video', and method 'by ID'. It effectively distinguishes from sibling search tools (pexels_search_photos, pexels_search_videos) which query by keywords.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a specific ID is known, contrasting with search tools. However, it does not explicitly state when not to use it or mention alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pexels_search_photosSearch Pexels PhotosA

Read-onlyIdempotent

Search for stock photos by query with optional filters for orientation, size, color, and locale. Returns 3-5 results with mandatory photographer attribution.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`orientation`	No
`size`	No
`color`	No
`locale`	No
`per_page`	No
`force_refresh`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`kind`	Yes
`creatorName`	Yes
`creatorUrl`	Yes
`pageUrl`	Yes
`previewUrl`	Yes
`mediaUrl`	Yes
`mediaMimeType`	Yes
`dimensions`	Yes
`avgColor`	Yes
`alt`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds valuable behavioral details: returns 3-5 results and requires photographer attribution, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, extremely concise, with no filler. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and annotations, the description covers core functionality well. It lacks mention of per_page and force_refresh, but is otherwise sufficient for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions four optional filters (orientation, size, color, locale), adding semantic context that they are filters. However, it omits per_page and force_refresh, and schema coverage is 0%. The added value is marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search for stock photos by query with optional filters', specifying verb and resource. It distinguishes from siblings (pexels_get_details for individual photos, pexels_search_videos for videos) by focusing on photo search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the purpose is clear, the description does not provide explicit guidance on when to use this tool versus its siblings or alternatives. Usage is implied but not contrasted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pexels_search_videosSearch Pexels VideosA

Read-onlyIdempotent

Search for stock videos by query with optional filters. Returns HD-quality .mp4 links with mandatory attribution.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`orientation`	No
`size`	No
`locale`	No
`per_page`	No
`force_refresh`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`kind`	Yes
`creatorName`	Yes
`creatorUrl`	Yes
`pageUrl`	Yes
`previewUrl`	Yes
`mediaUrl`	Yes
`mediaMimeType`	Yes
`dimensions`	Yes
`durationSeconds`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal read-only, non-destructive, idempotent behavior. The description adds value by disclosing that results are HD-quality .mp4 links with mandatory attribution, which are not implied by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action and key details. Every word earns its place with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, covering return values. The description adds helpful context on output format and attribution. Missing aspects like pagination and enum specifics are minor given overall clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description provides no individual parameter explanations. It only mentions 'optional filters' generically, failing to compensate for the missing schema descriptions of the 6 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for stock videos by query with optional filters. It mentions HD-quality .mp4 links and mandatory attribution, which distinguishes it from sibling tools like pexels_search_photos (photos) and pexels_get_details (details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for video searches via 'stock videos' and optional filters, but does not explicitly state when to use this tool over siblings. However, the tool name and context signals make the distinction clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: searching photos, searching videos, and getting details by ID. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent 'pexels_verb_noun' pattern using snake_case, making it predictable for an agent to infer functionality.

Tool Count4/5

Three tools is minimal but appropriate for a focused image/video search service. It covers the core workflow without unnecessary bloat.

Completeness4/5

The set covers search and retrieval of photos and videos, but lacks features like curated collections or trending content, which are minor omissions.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Pexafy
com.pexafy
Semantic search over free-to-use stock photos from 9 libraries: by words, image, or similar.
Search Image & Video Processing AI & Machine Learning
2
joj-image-search C
com.jojapi
Image Search: Fast and Simple Image Search API. You can get 100+ search results in one query!.
Image & Video Processing Search
11
brave AOAuth
ai.smithery
Visit https://brave.com/search/api/ for a free API key. Search the web, local businesses, images,…
Search Browser Automation Web Scraping
31,409
Openverse A
io.github.pipeworx-io
Openverse Creative-Commons image + audio search
Search Open Data
372

Related MCP Servers

MCP Image Extractor
Agent Orchestration Image & Video Processing Autonomous Agents
ifmelate
A
license
A
quality
C
maintenance
A Model Context Protocol server that extracts images from URLs or base64 data and converts them into a format suitable for LLM analysis, allowing AI models to process and understand visual content.
Updated 6 months ago (2026-02-28 14:28 UTC)
3
197
21
MIT
Pexels MCP Server
Image & Video Processing Search
nikola-arman
A
license
Not graded
quality
D
maintenance
Enables searching and retrieving high-quality stock photos from Pexels with advanced filtering options including orientation, size, color, and localization support.
Updated a year ago (2025-08-21 02:53 UTC)
32
ISC
Pexels MCP Server
Search Entertainment & Media
CaullenOmdahl
A
license
C
quality
F
maintenance
Enables AI models to search and retrieve photos, videos, and collections from Pexels via the Pexels API.
Updated a year ago (2025-06-01 15:13 UTC)
11
32
9
ISC
Pexels MCP Server
Search Art & Culture
bighadj22
F
license
Not graded
quality
D
maintenance
Enables searching and displaying high-quality, royalty-free photos from Pexels directly in ChatGPT conversations via an interactive gallery widget.
Updated a year ago (2025-10-16 22:23 UTC)
2

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/afshinator/mcp-server-pexels'

If you have feedback or need assistance with the MCP directory API, please join our Discord server