{
  "markdown": "# mcp-pexels — Pexels MCP server for Claude, Cursor, and other AI agents\n\n[![npm version](https://img.shields.io/npm/v/mcp-pexels.svg)](https://www.npmjs.com/package/mcp-pexels)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-pexels.svg)](https://www.npmjs.com/package/mcp-pexels)\n[![CI](https://github.com/developer-ishan/mcp-pexels/actions/workflows/ci.yml/badge.svg)](https://github.com/developer-ishan/mcp-pexels/actions/workflows/ci.yml)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Node ≥20](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](#requirements)\n[![MCP compatible](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)\n\n**A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the [Pexels API](https://www.pexels.com/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.**\n\n📦 **npm:** [mcp-pexels](https://www.npmjs.com/package/mcp-pexels) · 🏷 **Latest release:** [v1.0.0](https://github.com/developer-ishan/mcp-pexels/releases/tag/v1.0.0) · 💻 **Source:** [developer-ishan/mcp-pexels](https://github.com/developer-ishan/mcp-pexels)\n\n> Photos & videos provided by [Pexels](https://www.pexels.com).\n\n## Drop-in config\n\n```json\n{\n  \"mcpServers\": {\n    \"pexels\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-pexels\"],\n      \"env\": { \"PEXELS_API_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\nPaste into your MCP client's config, restart, and the nine `pexels_*` tools are live. Get a free key at <https://www.pexels.com/api/>.\n\n---\n\n## Table of contents\n\n- [What can you build with this?](#what-can-you-build-with-this)\n- [Capabilities — nine tools](#capabilities--nine-tools)\n- [Connect to your MCP client](#connect-to-your-mcp-client)\n  - [Claude Desktop](#claude-desktop)\n  - [Claude Code](#claude-code)\n  - [Cursor](#cursor)\n  - [Cline (VS Code)](#cline-vs-code)\n  - [Continue.dev](#continuedev)\n  - [Generic / other clients](#generic--other-clients)\n- [Example prompts](#example-prompts)\n- [How it compares](#how-it-compares)\n- [FAQ](#faq)\n- [Requirements](#requirements)\n- [Development](#development)\n- [Releasing](#releasing)\n- [Contributing](#contributing)\n- [Attribution & License](#attribution--license)\n\n---\n\n## What can you build with this?\n\nOnce `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:\n\n- **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.\n- **Blog post / social media drafting** — \"Suggest three thumbnail options for an article about remote work\" → returns three Pexels URLs with photographer credit.\n- **Background research for video editing** — \"Show me popular drone footage under 30 seconds in 4K\" → uses `pexels_popular_videos` with size and duration filters.\n- **Mood boards** — \"Build me a mood board of warm-toned coffee shop photos\" → searches with `color: \"orange\"`.\n- **Coding agents** — generate CSS/HTML with realistic placeholder imagery instead of `lorem-pixel` boxes.\n- **Curated collections** — pull a specific Pexels collection (e.g. company-owned shots tagged on Pexels) into the agent's context.\n\nBecause every response includes a `_rateLimit` object, the agent can self-throttle and respect the Pexels free-tier quota (200 req/hour, 20 000/month).\n\n---\n\n## Capabilities — nine tools\n\n| Domain | Tool | What it does |\n|---|---|---|\n| Photos | [`pexels_search_photos`](./docs/tools/pexels_search_photos.md) | Search photos by query with orientation / size / color / locale filters. |\n| Photos | [`pexels_curated_photos`](./docs/tools/pexels_curated_photos.md) | Fetch the Pexels team's real-time curated photo feed. |\n| Photos | [`pexels_get_photo`](./docs/tools/pexels_get_photo.md) | Retrieve a single photo by its numeric id. |\n| Videos | [`pexels_search_videos`](./docs/tools/pexels_search_videos.md) | Search videos by query with orientation / size / locale filters. |\n| Videos | [`pexels_popular_videos`](./docs/tools/pexels_popular_videos.md) | Fetch popular videos with optional width / height / duration constraints. |\n| Videos | [`pexels_get_video`](./docs/tools/pexels_get_video.md) | Retrieve a single video by its numeric id. |\n| Collections | [`pexels_featured_collections`](./docs/tools/pexels_featured_collections.md) | List Pexels featured collections. |\n| Collections | [`pexels_my_collections`](./docs/tools/pexels_my_collections.md) | List the authenticated user's own collections. |\n| Collections | [`pexels_collection_media`](./docs/tools/pexels_collection_media.md) | Retrieve the photos and videos inside a specific collection. |\n\nEach tool response is the raw Pexels JSON merged with a top-level `_rateLimit` field exposing `limit`, `remaining`, and `reset` (UNIX timestamp).\n\nSee [`docs/tools/`](docs/tools/) for per-tool parameter tables and example payloads.\n\n---\n\n## Connect to your MCP client\n\nAll paths below use `npx -y mcp-pexels` — no global install required. Replace `your_key_here` with a real Pexels API key.\n\n### Claude Desktop\n\n**Option 1 — one-click `.mcpb` install (recommended).** Download the latest `mcp-pexels-*.mcpb` from the [Releases page](https://github.com/developer-ishan/mcp-pexels/releases/latest), double-click the file, paste your Pexels API key when Claude Desktop prompts, and click Install.\n\n**Option 2 — manual JSON config.** Edit `claude_desktop_config.json`:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"pexels\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-pexels\"],\n      \"env\": { \"PEXELS_API_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\n### Claude Code\n\n```bash\nclaude mcp add pexels -e PEXELS_API_KEY=your_key_here -- npx -y mcp-pexels\n```\n\nOr edit `~/.claude.json` directly and add the same `mcpServers` block as above.\n\n### Cursor\n\nEdit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):\n\n```json\n{\n  \"mcpServers\": {\n    \"pexels\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-pexels\"],\n      \"env\": { \"PEXELS_API_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\n### Cline (VS Code)\n\nOpen the Cline extension settings → **MCP Servers** → **Edit Settings**. Add:\n\n```json\n{\n  \"mcpServers\": {\n    \"pexels\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-pexels\"],\n      \"env\": { \"PEXELS_API_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\n### Continue.dev\n\nIn `~/.continue/config.json`:\n\n```json\n{\n  \"experimental\": {\n    \"modelContextProtocolServers\": [\n      {\n        \"transport\": {\n          \"type\": \"stdio\",\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"mcp-pexels\"],\n          \"env\": { \"PEXELS_API_KEY\": \"your_key_here\" }\n        }\n      }\n    ]\n  }\n}\n```\n\n### Generic / other clients\n\nIf 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:\n\n```bash\nexport PEXELS_API_KEY=your_key_here\nnpx -y @modelcontextprotocol/inspector npx -y mcp-pexels\n```\n\nThis opens a browser UI where you can call each tool interactively.\n\n---\n\n## Example prompts\n\nOnce connected, try prompts like:\n\n- *\"Find me five landscape photos of mountains at golden hour. Make sure they're at least full HD.\"*\n- *\"Get me popular Pexels videos shorter than 15 seconds, 1080p or higher, of city traffic.\"*\n- *\"Pull photo id 2014422 and tell me the photographer.\"*\n- *\"List the featured Pexels collections — I want one I can browse for cooking photos.\"*\n- *\"Search videos of 'forest' in portrait orientation; pick the highest-quality HD file for me.\"*\n- *\"Show me Pexels photos with predominantly orange tones suitable for a fall-themed newsletter header.\"*\n\nThe agent will pick the appropriate tool, send the right parameters, and include photographer/videographer credit as part of its answer.\n\n---\n\n## How it compares\n\n| | mcp-pexels | Raw Pexels REST API | Image-only general MCP servers |\n|---|---|---|---|\n| Photos | ✅ | ✅ | varies |\n| Videos | ✅ | ✅ | usually ❌ |\n| Collections | ✅ | ✅ | ❌ |\n| Rate-limit headers exposed to agent | ✅ | ❌ (raw headers, agent must parse) | ❌ |\n| Zod-validated input | ✅ | ❌ | varies |\n| `npx`-installable, zero config | ✅ | ❌ | varies |\n| Type-safe TS source | ✅ | n/a | varies |\n| MIT-licensed | ✅ | n/a | varies |\n\nIf 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.\n\n---\n\n## FAQ\n\n### How do I get a Pexels API key?\n\nSign up at <https://www.pexels.com/api/> — keys are issued instantly and the free tier allows **200 requests/hour** and **20 000 requests/month**.\n\n### Does this cost anything?\n\nNo. The Pexels API is free, the npm package is free (MIT), and `mcp-pexels` itself does not call any paid service.\n\n### Will this work offline?\n\nNo — the server is a thin wrapper over the Pexels HTTPS API and requires network access.\n\n### Can I use Pexels content commercially?\n\nYes, per the Pexels license, but you must attribute the platform and (when possible) the photographer. See [Attribution](#attribution--license).\n\n### Does it work with Claude.ai (browser)?\n\nClaude.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.\n\n### Is there a hosted / SaaS version?\n\nNo. Run it locally via `npx`. Because Pexels API keys are per-user, hosting a shared instance doesn't make sense.\n\n### How do I update to a newer version?\n\n`npx` always fetches the latest published version. If you've installed globally, run `npm update -g mcp-pexels`.\n\n### Can I add more Pexels endpoints?\n\nThe Pexels API surface is fully implemented (9/9 endpoints as of Pexels API v1). New endpoints will be added via PR — see [Contributing](#contributing).\n\n### Does it work with `@modelcontextprotocol/inspector`?\n\nYes:\n\n```bash\nexport PEXELS_API_KEY=your_key_here\nnpx -y @modelcontextprotocol/inspector npx -y mcp-pexels\n```\n\n### How is rate limiting handled?\n\nEvery 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.\n\n### Where does my API key go?\n\nIt 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.\n\n---\n\n## Requirements\n\n- Node.js **≥ 20** (uses native `fetch` and `--env-file`)\n- A free Pexels API key — [request one here](https://www.pexels.com/api/)\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/developer-ishan/mcp-pexels.git\ncd mcp-pexels\nnpm install\necho \"PEXELS_API_KEY=your_key_here\" > .env\n\nnpm test           # 42 mocked vitest cases, no network\nnpm run build      # tsc → dist/\nnpm run dev        # tsx watch\nnpm run test:watch # vitest in watch mode\nnpm start          # node --env-file=.env dist/index.js\n```\n\n### Project layout\n\n```\nsrc/\n├── index.ts                  # MCP server entrypoint (stdio)\n├── http/\n│   ├── client.ts             # PexelsClient (injectable fetch for tests)\n│   └── types.ts              # PexelsApiError, RateLimit, PexelsResponse\n├── tools/\n│   ├── index.ts              # composes the three domain factories\n│   ├── photos.ts             # 3 photo tools\n│   ├── videos.ts             # 3 video tools\n│   └── collections.ts        # 3 collection tools\n└── types/\n    ├── tool.ts               # defineTool helper + ToolDefinition\n    ├── photos.ts\n    ├── videos.ts\n    └── collections.ts\n\ntests/\n├── helpers/mockClient.ts     # makeMockClient() — fake fetch via vitest mocks\n├── photos.test.ts            # 17 cases\n├── videos.test.ts            # 13 cases\n└── collections.test.ts       # 12 cases\n```\n\n### Testing approach\n\nTests construct a `PexelsClient` with a `vi.fn()` `fetchImpl` returned by `makeMockClient(responses)`. No real HTTP is performed. Each tool is exercised for:\n\n1. **Happy path** — URL serialization and `Authorization` header.\n2. **Error mapping** — non-2xx → `PexelsApiError` with `status` and `body`.\n3. **Zod validation** — required params, enum membership, integer bounds.\n\n---\n\n## Releasing\n\nThis repo uses a tag-driven release workflow (`.github/workflows/release.yml`):\n\n1. Bump the version: `npm version patch` (or `minor` / `major`) — creates a commit and tag.\n2. Push: `git push && git push --tags`.\n3. The workflow runs tests, builds, publishes to npm with provenance using the `NPM_TOKEN` repository secret, builds the **`.mcpb` bundle** via `npm run pack:mcpb`, and creates a GitHub release with auto-generated notes that includes the bundle as a downloadable asset.\n\nSee [`CHANGELOG.md`](./CHANGELOG.md) for version history.\n\n---\n\n## Contributing\n\nIssues and pull requests welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the development workflow and [`SECURITY.md`](./SECURITY.md) to report a vulnerability privately.\n\nIf you ship `mcp-pexels` inside a tool or product, open a PR adding it to the \"Used by\" list in [`CONTRIBUTING.md`](./CONTRIBUTING.md).\n\n### Listed on / submit to\n\n- **[Smithery](https://smithery.ai/)** — auto-discovered via [`smithery.yaml`](./smithery.yaml).\n- **[mcp.so](https://mcp.so)** — community directory.\n- **[awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)** — curated GitHub list.\n- **[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)** — Anthropic's official directory.\n\nSee [`docs/MARKETPLACES.md`](./docs/MARKETPLACES.md) for the submission cheatsheet.\n\n---\n\n## Attribution & License\n\nWhen you use Pexels content, please follow the [Pexels API guidelines](https://www.pexels.com/api/documentation/#guidelines):\n\n- Show a prominent link to Pexels — e.g. *\"Photos provided by Pexels\"*.\n- Credit photographers/videographers when possible — e.g. *\"Photo by John Doe on Pexels\"*.\n\nThe `mcp-pexels` package itself is released under the [MIT License](./LICENSE).\n",
  "bytes": 14433,
  "sha": "ea257d86b2da8d1153da6371e4aa3337abd266784d9c742d8e386133d303b8b3",
  "repo_slug": "developer-ishan/mcp-pexels",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_developer_ishan_pexels_269db6be/readme"
}