Pexels MCP Server: Setup, API Key and Limits

Q: Why does uvx pexels-mcp-server crash?

That is the garylab server. Its dependency on the mcp Python package has no upper bound, so a fresh install pulls in mcp 2.0, which breaks it. The fix suggested in issue #2 is to pin mcp<2.0.0. Until it is fixed upstream, use mcp-pexels instead.

Q: Does it download the images?

No. It returns Pexels JSON with image and video URLs in several sizes. Your agent or app loads the file from the URL.

Q: Does it work in claude.ai in the browser?

Not as a local server. It runs over stdio, so use Claude Desktop, Claude Code, Cursor or another client that starts local servers. The README says there is no hosted version.

On this page

Pexels MCP Server: Setup, Free API Key and Safe Use (Nov 2026)

Pexels has no official MCP server. The community Pexels MCP server that works today is mcp-pexels. To set it up, get a free Pexels API key and run claude mcp add pexels -e PEXELS_API_KEY=your_key_here -- npx -y mcp-pexels (Claude Desktop and Cursor use a JSON config, below). It searches and fetches free Pexels photos, videos and collections. TrustedMCP grades it C: it is read-only and local, but has one maintainer and one all-purpose key.

What the Pexels MCP server does

mcp-pexels is an MIT-licensed TypeScript server by GitHub user developer-ishan. It runs on your machine over stdio and calls the Pexels API. Its README lists nine tools:

Area	Tool	What it does
Photos	`pexels_search_photos`	Search photos, with orientation, size, colour and locale filters
Photos	`pexels_curated_photos`	The Pexels team's curated photo feed
Photos	`pexels_get_photo`	One photo by its numeric id
Videos	`pexels_search_videos`	Search videos, with orientation, size and locale filters
Videos	`pexels_popular_videos`	Popular videos, with width, height and duration limits
Videos	`pexels_get_video`	One video by its numeric id
Collections	`pexels_featured_collections`	Pexels' featured collections
Collections	`pexels_my_collections`	Your own collections
Collections	`pexels_collection_media`	The photos and videos in one collection

Every tool sends a GET request. Nothing uploads, likes or deletes. Each answer is the raw Pexels JSON plus a _rateLimit object (limit, remaining, reset), so the agent can see how much of your quota is left.

The server returns links and metadata, not image files. Your agent picks a photo and gives you its URL and photographer, or puts the URL into the page or slide it is building.

Why not the other Pexels MCP servers?

When we checked on 2026-11-01:

garylab/pexels-mcp-server (PyPI pexels-mcp-server) has the most GitHub stars, but a fresh uvx pexels-mcp-server install crashes on startup. Its mcp>=1.6.0 dependency now resolves to mcp 2.0, which removed an API the server uses (issue #2, open since August 2026). The last commit was in November 2025.
mcp-pexels has the most npm downloads of the Pexels servers in the official MCP Registry (790 in the 30 days to 2026-10-29). That is why we listed it.
Others in the registry include @hanoak/pexels-mcp-server, a Rust server from codeChap, and a hosted Pipeworx gateway. We haven't graded them.

How to get a free Pexels API key

Make a free account at pexels.com.
Go to pexels.com/api and request a key. Pexels' docs say: "Anyone with a Pexels account can request an API key, which you will receive instantly."
Copy the key into an environment variable called PEXELS_API_KEY. Don't paste it into a file you commit (see where to keep it).

The API is free. The server sends the key as the Authorization header to api.pexels.com, the format Pexels' docs ask for.

Pexels MCP setup in Claude Code, Claude Desktop and Cursor

You need Node.js 20 or newer. The snippets below come from the mcp-pexels README. your_key_here is a placeholder.

Claude Code:

claude mcp add pexels -e PEXELS_API_KEY=your_key_here -- npx -y mcp-pexels

Run claude mcp list afterwards to check it connects. More options, including scopes, are in our Claude Code MCP setup guide.

Claude Desktop. The README's recommended route is the one-click .mcpb bundle from the project's Releases page: double-click it and paste your key when Claude Desktop asks. Or edit claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/):

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "mcp-pexels"],
      "env": { "PEXELS_API_KEY": "your_key_here" }
    }
  }
}

Restart Claude Desktop after editing.

Cursor. Use the same JSON in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

Test it on its own first. The README's MCP Inspector line lets you call each tool by hand:

export PEXELS_API_KEY=your_key_here
npx -y @modelcontextprotocol/inspector npx -y mcp-pexels

Keep the key in an environment variable

The README's snippets put the key straight into the config file. That is fine on your own machine, but not in a file you share or commit.

Claude Code: claude mcp add -e stores the value in ~/.claude.json for local and user scope. For a shared .mcp.json, write "PEXELS_API_KEY": "${PEXELS_API_KEY}" and set the variable in your shell.
Cursor: use the global ~/.cursor/mcp.json, or write "${env:PEXELS_API_KEY}" in a project file.
Never commit the key. If it ends up in a repo, treat it as leaked.

The full method for each client is in how to keep API keys out of MCP config files.

Pexels API rate limits and licence

From Pexels' API documentation:

Rate limit: "200 requests per hour and 20,000 requests per month" by default. Successful responses carry X-Ratelimit-Limit, X-Ratelimit-Remaining and X-Ratelimit-Reset (a UNIX timestamp for the monthly reset). A 429 Too Many Requests means you are over. mcp-pexels passes the 429 back to the agent as an error.
Higher limits: you can ask Pexels for more. The docs say "If you meet our API terms, you can get unlimited requests for free." Be ready to show how you credit Pexels.
API guidelines: show "a prominent link to Pexels" wherever you use API results, credit photographers when possible, don't copy Pexels' core functionality (a wallpaper app is the docs' example), and don't try to get around the rate limit. Pexels says that can end your API access.

From the Pexels licence: all photos and videos can be downloaded and used for free, and you can edit them. Attribution is not required, though the API guidelines above still ask for a Pexels link. You may not:

show identifiable people in a bad light or in an offensive way;
sell unaltered copies;
imply that people or brands in the picture endorse your product;
redistribute or sell the files on other stock photo or wallpaper sites;
use them as part of a trademark, design mark, trade name, business name or service mark.

An agent won't check these rules for you. If it picks a photo of a person for an ad, you still have to judge whether the use fits.

Why the Pexels MCP server grades C

Scored against our rubric:

Authentication, 10 of 30. This is the biggest deduction. Pexels gives one API key per account. Its docs describe no scopes, read-only keys or per-tool limits, and the key sits in your client config. The damage from a leak is limited, because the API only reads public stock media plus your own collections. Someone with your key can use up your quota or break the API terms in your name.
Maintenance, 10 of 25. One maintainer wrote and released the server on 2026-05-18, and nothing has been committed since. That was 167 days before this check, inside the 60-180 day band.
Known CVEs, 25 of 25. No advisories in OSV or on the GitHub repo. The repo has a SECURITY.md with private reporting.
Transport, 14 of 20. stdio only, with no shell commands. Inputs are checked with zod, and every request goes to api.pexels.com. That is the right setup for a local tool. HTTP would add nothing here.

Overall: grade C. More detail is on the Pexels MCP listing.

Safer-use tips

Pin the version. npx -y mcp-pexels runs the newest version published to npm every time. Use npx -y mcp-pexels@1.0.2 (the current release) and upgrade on purpose after reading the changelog.
Keep the key out of shared files (see above), and keep this key for this server only.
Treat returned text as untrusted. Photo descriptions, photographer names and collection titles are written by Pexels users. They reach your agent as input and could carry injected instructions. Keep tool approval on for anything that writes files or runs commands. Our guide to MCP server security risks explains why.
Watch the quota. Ask the agent for fewer, more specific searches. The _rateLimit field in each answer shows what is left.
Credit Pexels in what you publish. Ask the agent to add "Photo by [name] on Pexels" with a link. That follows the API guidelines and helps if you ever ask for a higher limit.

Frequently asked questions

Is there an official Pexels MCP server?

No. When we checked on 2026-11-01, Pexels had not released one, and every Pexels server in the official MCP Registry was a community project. We list mcp-pexels because it works on a fresh install and is the most downloaded.

How do I get a Pexels API key?

Make a free account at pexels.com, then request a key at pexels.com/api. Pexels' docs say anyone with an account can request one, "which you will receive instantly." Put it in the PEXELS_API_KEY environment variable that mcp-pexels reads.

Is the Pexels API free?

Yes. The key is free and the default limit is 200 requests an hour and 20,000 a month. Pexels can raise the limit for free if your use follows its API terms.

What are the Pexels API rate limits?

200 requests per hour and 20,000 per month by default. Each mcp-pexels answer includes a _rateLimit object showing what is left, and going over returns a 429 Too Many Requests error.

Can I use Pexels photos in ads or client work?

The licence says all photos and videos "can be downloaded and used for free", and the uses it lists include ads and marketing campaigns. The restrictions above still apply: for example, you can't sell unaltered copies or imply that the people shown endorse your product.

Do I have to credit the photographer?

The licence doesn't require it. The API guidelines ask you to show a prominent link to Pexels and to credit photographers when possible, so do both when the images came through the API.

Why does `uvx pexels-mcp-server` crash?

That is the garylab server. Its dependency on the mcp Python package has no upper bound, so a fresh install pulls in mcp 2.0, which breaks it. The fix suggested in issue #2 is to pin mcp<2.0.0. Until it is fixed upstream, use mcp-pexels instead.

Does it download the images?