Pexels MCP Server
Provides tools for searching and retrieving photos, videos, and collections from Pexels, with support for filters like orientation, size, color, and locale, as well as direct download links for media.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Pexels MCP Serversearch for photos of a sunset at the beach"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Pexels MCP Server
A Model Context Protocol (MCP) server that provides access to the Pexels API, allowing AI models to search for and retrieve photos, videos, and collections from Pexels.
Features
Search for photos and videos by query, orientation, size, and color
Access curated and popular content from Pexels
Browse Pexels collections
Get detailed information about specific photos and videos
Access content via tools or direct URI resources
Related MCP server: mcp-server-pexels
Requirements
Node.js 18 or higher
A Pexels API key (get one at https://www.pexels.com/api/)
Local Development
Clone the repository
Install dependencies
pnpm installBuild the project
pnpm buildRun in development mode
PEXELS_API_KEY=your_api_key pnpm dev
Deploying to Smithery
This MCP server is ready to be deployed to Smithery. Follow these steps:
Add the server to Smithery or claim an existing server
Go to the Deployments tab (only visible to authenticated owners)
Deploy the server
When configuring the deployment, provide your Pexels API key in the configuration settings
API Usage
The server provides the following tools:
Photo Tools
searchPhotos: Search for photos by query (use descriptive keywords for relevant results, e.g., 'Thai hotel reception', 'red sports car driving', not just 'hotel' or 'car'; combine with parameters likeorientation,size,color, andlocalefor refined results), with optional filters for orientation, size, color, locale (e.g., 'en-US', 'es-ES'), page, and results per page. Returns metadata including photo IDs and URLs, plus current API rate limit status.downloadPhoto: Fetches a specific photo by its ID and desired size (optional, defaults to 'original'). Available sizes: 'original', 'large2x', 'large', 'medium', 'small', 'portrait', 'landscape', 'tiny'. Returns a direct download link for the requested image size, suggested filename (including size), and attribution information. The AI client should use its available local tools (likecurlor PowerShell'sInvoke-WebRequest) to download the photo using the provided link.getCuratedPhotos: Retrieve a curated set of photos from Pexels, optionally paginated.getPhoto: Retrieve detailed information about a specific photo by its ID.
Video Tools
searchVideos: Search for videos by query (use descriptive keywords for relevant results, e.g., 'drone footage beach sunset', 'time lapse city traffic', not just 'beach' or 'city'; combine with parameters likeorientationandsizefor refined results), with optional filters for orientation, size, locale (e.g., 'en-US', 'es-ES'), page, and results per page. Returns metadata including video IDs and URLs, plus current API rate limit status.getPopularVideos: Retrieve a list of popular videos from Pexels, with optional filters for dimensions, duration, page, and results per page.getVideo: Retrieve detailed information about a specific video by its ID.downloadVideo: Fetches a specific video by its ID and preferred quality (hd/sd). Returns a direct download link, suggested filename, and attribution information. The AI client should use its available local tools (likecurlor PowerShell'sInvoke-WebRequest) to download the video using the provided link.
Collection Tools
getFeaturedCollections: Retrieve a list of featured collections from Pexels, optionally paginated.: (Commented out in code) Requires OAuth 2.0 authentication, not supported by this server.getMyCollectionsgetCollectionMedia: Retrieve media items (photos or videos) from a specific collection by collection ID, with optional filters for type, sort order, page, and results per page.
Resources
The server provides the following URI-addressable resources:
pexels-photo://{id}: Access a specific photo by IDpexels-video://{id}: Access a specific video by IDpexels-collection://{id}: Access a specific collection by ID
Error Handling
The server attempts to provide informative error messages for common issues like invalid API keys, rate limits, or missing resources. Successful responses also include the current Pexels API rate limit status (remaining requests, reset time) in the output.
Attribution Requirements
When using the Pexels API, you must follow their attribution requirements:
Always show a prominent link to Pexels (e.g., "Photos provided by Pexels")
Always credit photographers (e.g., "Photo by John Doe on Pexels")
License
ISC
Available Tools
11 toolsdownloadPhotoD
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the photo to download | |
| size | No | Desired photo size/version to download | original |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
downloadVideoD
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the video to download | |
| quality | No | Preferred video quality (hd or sd) | hd |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getCollectionMediaD
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the collection | |
| type | No | Filter by media type | |
| sort | No | Sort order | |
| page | No | Page number | |
| perPage | No | Results per page (max 80) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getCuratedPhotosD
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| perPage | No | Results per page (max 80) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getFeaturedCollectionsD
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| perPage | No | Results per page (max 80) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getPhotoD
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the photo to retrieve |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getPopularVideosD
| Name | Required | Description | Default |
|---|---|---|---|
| minWidth | No | Minimum video width in pixels | |
| minHeight | No | Minimum video height in pixels | |
| minDuration | No | Minimum video duration in seconds | |
| maxDuration | No | Maximum video duration in seconds | |
| page | No | Page number | |
| perPage | No | Results per page (max 80) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getVideoD
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the video to retrieve |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchPhotosD
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query. Use descriptive keywords for relevant results (e.g., 'Thai hotel reception', 'red sports car driving', not just 'hotel' or 'car'). Combine with parameters like 'orientation', 'size', and 'color' for refined results. | |
| orientation | No | Desired photo orientation | |
| size | No | Minimum photo size | |
| color | No | Desired photo color (e.g., 'red', 'blue', '#ff0000') | |
| page | No | Page number | |
| perPage | No | Results per page (max 80) | |
| locale | No | The locale of the search query (e.g., 'en-US', 'es-ES'). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchVideosD
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query. Use descriptive keywords for relevant results (e.g., 'drone footage beach sunset', 'time lapse city traffic', not just 'beach' or 'city'). Combine with parameters like 'orientation' and 'size' for refined results. | |
| orientation | No | Desired video orientation | |
| size | No | Minimum video size | |
| page | No | Page number | |
| perPage | No | Results per page (max 80) | |
| locale | No | The locale of the search query (e.g., 'en-US', 'es-ES'). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
setApiKeyD
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | Yes | Your Pexels API key |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v1.0.0- First observed
downloadPhoto - First observed
downloadVideo - First observed
getCollectionMedia - First observed
getCuratedPhotos - First observed
getFeaturedCollections - First observed
getPhoto - First observed
getPopularVideos - First observed
getVideo - First observed
searchPhotos - First observed
searchVideos - First observed
setApiKey
TDQS
Scored across 11 tools
Tool names are distinct by resource (photo, video, collection) and action (get, search, download), but without descriptions, subtle overlaps like 'downloadPhoto' vs 'getPhoto' could confuse an agent.
All tools use consistent camelCase with a verb_noun pattern (e.g., downloadPhoto, searchVideos, setApiKey), no mixing of conventions.
11 tools cover the essential operations of the Pexels API (search, individual retrieval, curated/popular, collections, download, API key configuration) without being excessive.
The tool set covers major read operations and collections, but may lack some features like listing all collections or more detailed filtering, and no descriptions hinder full assessment.
Maintenance
Related MCP Connectors
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Real-time web search, reasoning, and research through Perplexity's API
Search Google straight from your AI agent. Web results, images, videos, news, products, scholarly ar
Give AI assistants access to real-time data. Search the web, compare flights, find hotels, and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving high-quality stock photos from Pexels with advanced filtering options including orientation, size, color, and localization support.16 npmISC
- AlicenseAqualityCmaintenanceSearch and find free images and videos from Pexels.com. (free api key required)32MIT
- FlicenseNot gradedqualityDmaintenanceEnables searching and displaying high-quality, royalty-free photos from Pexels directly in ChatGPT conversations via an interactive gallery widget.2-
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving free photos and videos from Pexels using natural language queries, with support for filters like orientation, size, color, and duration.16 npmISC