Pexels MCP server
✓ VerifiedAllows AI agents to search and retrieve royalty-free stock photos, videos, and curated collections from the Pexels API.
Also known as developer-ishan/mcp-pexels, mcp-pexels
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.2
- Last commit
- May 18, 2026
- License
- MIT
What is Pexels MCP?
Pexels allows AI agents to search and retrieve royalty-free stock photos, videos, and curated collections from the Pexels API.
Summary generated from the project's README
About Pexels MCP server
Finding royalty-free stock media for creative projects is what this server enables for developers using AI agents. It provides direct access to the Pexels API, allowing clients like Claude Desktop, Cursor, and Cline to search for and retrieve high-quality photos, videos, and curated collections. By connecting via npx, users can integrate visual assets directly into their chat workflows without leaving their development environment.
The server includes nine specialized tools covering three main domains: photos, videos, and collections. Users can perform granular searches using filters for orientation, size, color, and duration. It is designed to be aware of API constraints, providing a rate limit object in every response so the agent can monitor the remaining quota of 200 requests per hour. This setup requires a Pexels API key provided via an environment variable to function.
What you can do with it
- 1Generate social media thumbnailsDevelopers can ask an agent to suggest multiple visual options for article thumbnails.
- 2Source video background footageUsers can request specific video types, such as 4K drone footage with duration constraints.
- 3Create visual mood boardsAn agent can build a collection of images based on specific color themes.
Written from the project's README. Every use case is checked against a quote from it.
How to install Pexels MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Pexels MCP in Claude Code
$ claude mcp add --env 'PEXELS_API_KEY=<YOUR_PEXELS_API_KEY>' mcp-pexels -- npx -y mcp-pexelsInstall Pexels MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-pexels": {
"command": "npx",
"args": [
"-y",
"mcp-pexels"
],
"env": {
"PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>"
}
}
}
}Install Pexels MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-pexels": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-pexels"
],
"env": {
"PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>"
}
}
}
}Install Pexels MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-pexels","type":"stdio","command":"npx","args":["-y","mcp-pexels"],"env":{"PEXELS_API_KEY":"<YOUR_PEXELS_API_KEY>"}}'Install Pexels MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-pexels": {
"command": "npx",
"args": [
"-y",
"mcp-pexels"
],
"env": {
"PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>"
}
}
}
}Install Pexels MCP in Codex
$ codex mcp add mcp-pexels --env 'PEXELS_API_KEY=<YOUR_PEXELS_API_KEY>' -- npx -y mcp-pexelsInstall Pexels MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-pexels] command = "npx" args = ["-y", "mcp-pexels"] [mcp_servers.mcp-pexels.env] PEXELS_API_KEY = "<YOUR_PEXELS_API_KEY>"
Install Pexels MCP in Gemini CLI
$ gemini mcp add -s user -e 'PEXELS_API_KEY=<YOUR_PEXELS_API_KEY>' mcp-pexels npx -- -y mcp-pexelsInstall Pexels MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-pexels": {
"command": "npx",
"args": [
"-y",
"mcp-pexels"
],
"env": {
"PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>"
}
}
}
}Configuration
PEXELS_API_KEYRequiredSecretPexels API key. Get one for free at https://www.pexels.com/api/. Free tier: 200 req/hour, 20,000 req/month.
| Name | Description | |
|---|---|---|
| PEXELS_API_KEY | Pexels API key. Get one for free at https://www.pexels.com/api/. Free tier: 200 req/hour, 20,000 req/month. | RequiredSecret |
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledeveloper-ishan/mcp-pexels is public and reachablegithub.com/developer-ishan/mcp-pexels ↗Pass
- Package names this repository as its sourcemcp-pexels names developer-ishan/mcp-pexels as sourcenpmjs.com/package/mcp-pexels ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for mcp-pexelsnpmjs.com/package/mcp-pexels/v/1.0.2#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-05-18github.com/developer-ishan/mcp-pexels ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mcp-pexelsPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-pexels — Pexels MCP server for Claude, Cursor, and other AI agents
A Model Context Protocol server that exposes the Pexels API — free stock photos, videos, and curated collections — as MCP tools that any compatible AI client (Claude Desktop, Claude Code, Cursor, Cline, Continue, etc.) can call directly from a chat.
📦 npm: mcp-pexels · 🏷 Latest release: v1.0.0 · 💻 Source: developer-ishan/mcp-pexels
Photos & videos provided by Pexels.
Drop-in config
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
Paste into your MCP client's config, restart, and the nine pexels_* tools are live. Get a free key at https://www.pexels.com/api/.
Table of contents
- What can you build with this?
- Capabilities — nine tools
- Connect to your MCP client
- Example prompts
- How it compares
- FAQ
- Requirements
- Development
- Releasing
- Contributing
- Attribution & License
What can you build with this?
Once mcp-pexels is connected to an AI client, the agent can pull royalty-free photos and videos straight into its workflow. A few concrete uses:
- Slide-deck and document illustration — "Find me a landscape photo of mountains at sunset for slide 3" → the agent searches Pexels, picks one, and embeds it.
- Blog post / social media drafting — "Suggest three thumbnail options for an article about remote work" → returns three Pexels URLs with photographer credit.
- Background research for video editing — "Show me popular drone footage under 30 seconds in 4K" → uses
pexels_popular_videoswith size and duration filters. - Mood boards — "Build me a mood board of warm-toned coffee shop photos" → searches with
color: "orange". - Coding agents — generate CSS/HTML with realistic placeholder imagery instead of
lorem-pixelboxes. - Curated collections — pull a specific Pexels collection (e.g. company-owned shots tagged on Pexels) into the agent's context.
Because every response includes a _rateLimit object, the agent can self-throttle and respect the Pexels free-tier quota (200 req/hour, 20 000/month).
Capabilities — nine tools
| Domain | Tool | What it does |
|---|---|---|
| Photos | pexels_search_photos |
Search photos by query with orientation / size / color / locale filters. |
| Photos | pexels_curated_photos |
Fetch the Pexels team's real-time curated photo feed. |
| Photos | pexels_get_photo |
Retrieve a single photo by its numeric id. |
| Videos | pexels_search_videos |
Search videos by query with orientation / size / locale filters. |
| Videos | pexels_popular_videos |
Fetch popular videos with optional width / height / duration constraints. |
| Videos | pexels_get_video |
Retrieve a single video by its numeric id. |
| Collections | pexels_featured_collections |
List Pexels featured collections. |
| Collections | pexels_my_collections |
List the authenticated user's own collections. |
| Collections | pexels_collection_media |
Retrieve the photos and videos inside a specific collection. |
Each tool response is the raw Pexels JSON merged with a top-level _rateLimit field exposing limit, remaining, and reset (UNIX timestamp).
See docs/tools/ for per-tool parameter tables and example payloads.
Connect to your MCP client
All paths below use npx -y mcp-pexels — no global install required. Replace your_key_here with a real Pexels API key.
Claude Desktop
Option 1 — one-click .mcpb install (recommended). Download the latest mcp-pexels-*.mcpb from the Releases page, double-click the file, paste your Pexels API key when Claude Desktop prompts, and click Install.
Option 2 — manual JSON config. Edit claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
Restart Claude Desktop.
Claude Code
claude mcp add pexels -e PEXELS_API_KEY=your_key_here -- npx -y mcp-pexels
Or edit ~/.claude.json directly and add the same mcpServers block as above.
Cursor
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
Cline (VS Code)
Open the Cline extension settings → MCP Servers → Edit Settings. Add:
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
Continue.dev
In ~/.continue/config.json:
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
]
}
}
Generic / other clients
If your client supports stdio MCP servers it just needs command, args, and env. Use the same shape as Cursor / Claude Desktop above. For inspector / debugging:
export PEXELS_API_KEY=your_key_here
npx -y @modelcontextprotocol/inspector npx -y mcp-pexels
This opens a browser UI where you can call each tool interactively.
Example prompts
Once connected, try prompts like:
- "Find me five landscape photos of mountains at golden hour. Make sure they're at least full HD."
- "Get me popular Pexels videos shorter than 15 seconds, 1080p or higher, of city traffic."
- "Pull photo id 2014422 and tell me the photographer."
- "List the featured Pexels collections — I want one I can browse for cooking photos."
- "Search videos of 'forest' in portrait orientation; pick the highest-quality HD file for me."
- "Show me Pexels photos with predominantly orange tones suitable for a fall-themed newsletter header."
The agent will pick the appropriate tool, send the right parameters, and include photographer/videographer credit as part of its answer.
How it compares
| mcp-pexels | Raw Pexels REST API | Image-only general MCP servers | |
|---|---|---|---|
| Photos | ✅ | ✅ | varies |
| Videos | ✅ | ✅ | usually ❌ |
| Collections | ✅ | ✅ | ❌ |
| Rate-limit headers exposed to agent | ✅ | ❌ (raw headers, agent must parse) | ❌ |
| Zod-validated input | ✅ | ❌ | varies |
npx-installable, zero config |
✅ | ❌ | varies |
| Type-safe TS source | ✅ | n/a | varies |
| MIT-licensed | ✅ | n/a | varies |
If you only need photos and you already have a generic image MCP server wired up, that may be enough. If you want first-class video and collection support with rate-limit awareness, this is purpose-built for it.
FAQ
How do I get a Pexels API key?
Sign up at https://www.pexels.com/api/ — keys are issued instantly and the free tier allows 200 requests/hour and 20 000 requests/month.
Does this cost anything?
No. The Pexels API is free, the npm package is free (MIT), and mcp-pexels itself does not call any paid service.
Will this work offline?
No — the server is a thin wrapper over the Pexels HTTPS API and requires network access.
Can I use Pexels content commercially?
Yes, per the Pexels license, but you must attribute the platform and (when possible) the photographer. See Attribution.
Does it work with Claude.ai (browser)?
Claude.ai's web product doesn't yet support stdio MCP servers — only Claude Desktop, Claude Code, and the API do. Anthropic is rolling out browser MCP support, so this should change.
Is there a hosted / SaaS version?
No. Run it locally via npx. Because Pexels API keys are per-user, hosting a shared instance doesn't make sense.
How do I update to a newer version?
npx always fetches the latest published version. If you've installed globally, run npm update -g mcp-pexels.
Can I add more Pexels endpoints?
The Pexels API surface is fully implemented (9/9 endpoints as of Pexels API v1). New endpoints will be added via PR — see Contributing.
Does it work with @modelcontextprotocol/inspector?
Yes:
export PEXELS_API_KEY=your_key_here
npx -y @modelcontextprotocol/inspector npx -y mcp-pexels
How is rate limiting handled?
Every tool response includes a _rateLimit object with limit, remaining, and reset (UNIX timestamp). The agent can read this and self-throttle. If Pexels returns 429, the server surfaces it as a PexelsApiError so the agent sees the failure.
Where does my API key go?
It is read from the PEXELS_API_KEY env var on the local process. It never leaves your machine except in Authorization headers to api.pexels.com. Nothing is logged.
Requirements
- Node.js ≥ 20 (uses native
fetchand--env-file) - A free Pexels API key — request one here
Development
git clone https://github.com/developer-ishan/mcp-pexels.git
cd mcp-pexels
npm install
echo "PEXELS_API_KEY=your_key_here" > .env
npm test # 42 mocked vitest cases, no network
npm run build # tsc → dist/
npm run dev # tsx watch
npm run test:watch # vitest in watch mode
npm start # node --env-file=.env dist/index.js
Project layout
src/
├── index.ts # MCP server entrypoint (stdio)
├── http/
│ ├── client.ts # PexelsClient (injectable fetch for tests)
│ └── types.ts # PexelsApiError, RateLimit, PexelsResponse
├── tools/
│ ├── index.ts # composes the three domain factories
│ ├── photos.ts # 3 photo tools
│ ├── videos.ts # 3 video tools
│ └── collections.ts # 3 collection tools
└── types/
├── tool.ts # defineTool helper + ToolDefinition
├── photos.ts
├── videos.ts
└── collections.ts
tests/
├── helpers/mockClient.ts # makeMockClient() — fake fetch via vitest mocks
├── photos.test.ts # 17 cases
├── videos.test.ts # 13 cases
└── collections.test.ts # 12 cases
Testing approach
Tests construct a PexelsClient with a vi.fn() fetchImpl returned by makeMockClient(responses). No real HTTP is performed. Each tool is exercised for:
- Happy path — URL serialization and
Authorizationheader. - Error mapping — non-2xx →
PexelsApiErrorwithstatusandbody. - Zod validation — required params, enum membership, integer bounds.
Releasing
This repo uses a tag-driven release workflow (.github/workflows/release.yml):
- Bump the version:
npm version patch(orminor/major) — creates a commit and tag. - Push:
git push && git push --tags. - The workflow runs tests, builds, publishes to npm with provenance using the
NPM_TOKENrepository secret, builds the.mcpbbundle vianpm run pack:mcpb, and creates a GitHub release with auto-generated notes that includes the bundle as a downloadable asset.
See CHANGELOG.md for version history.
Contributing
Issues and pull requests welcome. See CONTRIBUTING.md for the development workflow and SECURITY.md to report a vulnerability privately.
If you ship mcp-pexels inside a tool or product, open a PR adding it to the "Used by" list in CONTRIBUTING.md.
Listed on / submit to
- Smithery — auto-discovered via
smithery.yaml. - mcp.so — community directory.
- awesome-mcp-servers — curated GitHub list.
- modelcontextprotocol/servers — Anthropic's official directory.
See docs/MARKETPLACES.md for the submission cheatsheet.
Attribution & License
When you use Pexels content, please follow the Pexels API guidelines:
- Show a prominent link to Pexels — e.g. "Photos provided by Pexels".
- Credit photographers/videographers when possible — e.g. "Photo by John Doe on Pexels".
The mcp-pexels package itself is released under the MIT License.
Pexels MCP questions
How do I add Pexels MCP to Claude Code?
Run claude mcp add --env 'PEXELS_API_KEY=<YOUR_PEXELS_API_KEY>' mcp-pexels -- npx -y mcp-pexels in your terminal. Add --scope user to make it available in every project.
How do I add Pexels MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does this cost anything?
No, the Pexels API and the npm package are both free to use.
Can I use Pexels content commercially?
Yes, you can use the content commercially under the Pexels license, though you should attribute the platform and photographer when possible.
Does it work with Claude.ai in the browser?
Currently, it does not work with the Claude.ai web product, as that version does not support stdio MCP servers. It works with Claude Desktop, Claude Code, and the API.