Pexels MCP Server

pexels-mcp-server

一个可用于生产环境的 Model Context Protocol（MCP）服务，为 Pexels API 提供支持。它为 AI 助手（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 及任何 MCP 客户端）提供工具，用于搜索和获取 Pexels 照片、视频及合集，涵盖 Pexels API 文档中的所有端点。

重要

非官方项目。 本项目与 Pexels 无关，未获得 Pexels 认可或赞助。“Pexels”是其各自所有者的商标。使用本项目时，您需使用自己的 Pexels API 账户，并负责遵守 Pexels 许可协议。

目录

• 功能
• 快速开始
• 交互示例
• 配置
• 工具
  • 工具参考
  • 输出格式
  • 资源与提示词
• 提示词示例
• 许可与合规
• 速率限制
• Pexels 文本的处理
• 隐私与安全
• 故障排除
• 常见问题
• 要求
• 兼容性
• 路线图
• 贡献
• 联系与社区
• 许可

功能

• 9 个工具，涵盖 Pexels 文档中的所有端点——照片（搜索、精选、获取）、视频（搜索、热门、获取）和合集（精选、媒体、我的合集）。Pexels 只有一个 API 密钥认证级别，且没有写入端点，因此不存在不完整的“只读 v1”——本项目覆盖了全部功能。
• 设计上充分考虑许可要求——Pexels 不要求署名，但每张照片都会返回可直接使用的致谢信息 credit（文本 + HTML）；服务的指令也会引导模型遵守适用的许可限制（不得转售未经修改的内容、不得将内容重新分发至其他图库平台、不得使用商标或徽标、不得暗示获得认可）。
• 真实的图像与视频 URL——每张照片都会返回 Pexels 自带的预设尺寸 src URL（original/large2x/large/medium/small/portrait/landscape/tiny）；每段视频都会返回其 video_files 版本（列表结果仅保留最高分辨率的几个版本，单条查询则返回全部版本）。
• 节省令牌的输出——将完整的 Pexels 响应精简为紧凑格式（以文本形式返回 URL + 元数据，绝不返回 base64 数据块），以缩小模型上下文。
• 稳健可靠——以 MCP isError 结果返回类型化错误，让模型能够恢复；同时支持重试/退避、超时和感知速率限制的配额快速拦截（Pexels 在返回 429 时会省略速率限制标头，因此客户端会缓存最近一次已知的重置时间，而不是进行猜测）。
• 安全——所有错误输出都会隐藏 API 密钥，并提供处理不可信文本的指引，以防范间接提示词注入。
• 轻量且现代——ESM、Node 20+，通过 npx 无需安装即可使用，不收集遥测数据。

快速开始

1. 获取 Pexels API 密钥

在 pexels.com/api 免费创建账户后，即可立即获得 API 密钥——无需应用审核，也无需等待审批。

2. 将服务添加到 MCP 客户端

Claude Desktop — 编辑 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "@hanoak/pexels-mcp-server"],
      "env": {
        "PEXELS_API_KEY": "your_api_key"
      }
    }
  }
}

重启客户端。支持的所有变量请参阅配置。

claude mcp add pexels \
  --env PEXELS_API_KEY=your_api_key \
  -- npx -y @hanoak/pexels-mcp-server

{
  "servers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "@hanoak/pexels-mcp-server"],
      "env": {
        "PEXELS_API_KEY": "your_api_key"
      }
    }
  }
}

PEXELS_API_KEY=your_api_key npx -y @hanoak/pexels-mcp-server

3. 试用

重启客户端并提出以下请求：

“在 Pexels 上帮我找一张山脉的照片。”

交互示例

典型流程：模型调用 pexels_search_photos，挑选一项结果，并附上致谢署名来展示图片。

你： 找一张雾气笼罩的松林风景照。

助手： （调用 pexels_search_photos，参数为 query: "foggy pine forest"、orientation: "landscape"，并挑选最佳结果） 这张很合适——照片由 Jane Doe 上传至 Pexels，并附有图片 URL 和可直接使用的署名文本。

每个工具都会返回简洁的 JSON 载荷。下面是单张照片结果的结构示例（数值仅作说明）：

{
  "photo": {
    "id": 1103970,
    "alt": "Photography of Trees at Foggy Forest",
    "width": 4000,
    "height": 2667,
    "avg_color": "#3E361F",
    "url": "https://www.pexels.com/photo/photography-of-trees-at-foggy-forest-1103970/",
    "src": {
      "original": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg",
      "large2x": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=650&w=940",
      "large": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=650&w=940",
      "medium": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=350",
      "small": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=130",
      "portrait": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=1200&w=800",
      "landscape": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=627&w=1200",
      "tiny": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&dpr=1&fit=crop&h=200&w=280"
    },
    "photographer": {
      "name": "Jane Doe",
      "url": "https://www.pexels.com/@janedoe",
      "id": 42
    },
    "credit": {
      "text": "Photo by Jane Doe on Pexels",
      "html": "Photo by <a href=\"https://www.pexels.com/@janedoe\">Jane Doe</a> on <a href=\"https://www.pexels.com\">Pexels</a>"
    }
  },
  "rate_limit": { "limit": 200, "remaining": 199, "resetEpoch": 1755000000 }
}

配置

配置完全通过环境变量设置——无需配置文件，也无需用于保存密钥的标志。

支持 CLI 标志：--version 和 --help（例如 npx @hanoak/pexels-mcp-server --version）。

工具

所有工具都使用 pexels_* 命名空间，并且全部为只读（readOnlyHint: true）——Pexels API 没有写入端点，因此客户端可以安全地自动批准整个服务。per_page 的上限为 80（Pexels 文档规定的最大值），page 从 1 开始计数。

工具参考

工具返回经过精简、节省 token 的 JSON，而不是原始 Pexels 响应：

• 照片 → id、alt、width/height、avg_color、url、src（全部 8 种 Pexels 尺寸）、photographer 和致谢 credit 对象。
• 视频 → id、url、image、width/height、duration、user、video_files（列表结果中按分辨率取前 5 个；pexels_get_video 中提供完整列表）、video_files_count、preview_picture、video_pictures_count。
• 合集 → id、title、description、private、media_count、photos_count、videos_count。
• 每个结果都包含 rate_limit（limit、remaining、resetEpoch）；列表/搜索结果还会添加分页字段（total_results、page、per_page、has_next_page）。

资源和提示词

除了工具外，该服务还提供：

• 资源 — 客户端可提取并作为上下文使用的精简指南：

  • pexels://guides/usage — 适用的许可限制、可选的致谢惯例以及内容安全说明。

• 提示词 — 客户端可直接展示的现成任务；每项都会展开为引导式的多步骤工具调用任务：

  提示词	参数	功能
  find_photo	subject（必填）、orientation?	搜索一张照片，并附上致谢信息。
  photo_gallery	theme（必填）、count?、orientation?、color?	创建一组主题照片（最多 10 张），每张都附上致谢信息。
  find_video	subject（必填）、orientation?	搜索一个视频，并附上致谢信息。
  collection_tour	theme（必填）、count?	查找匹配的精选合集，并逐一浏览其中的媒体内容。
  media_brief	theme（必填）、photo_count?、video_count?	收集某个主题的照片和视频，并一并呈现。

提示词示例

可自然映射到这些工具的自然语言请求：

• “找一张日出时雾气笼罩的森林照片。”
• “在 Pexels 上搜索 5 张横向构图的极简风格工作空间照片。”
• “找一个海浪拍打礁石的视频。”
• “给我看看 Pexels 上精选的城市建筑主题合集。”
• “帮我制作一份包含照片和视频片段的混合媒体简报，主题是舒适的秋日清晨。”

许可与合规

与许多图库 API 相比，Pexels 的许可限制较少：无需署名（“感谢署名，但并非必须”）。每个照片结果仍会附带可直接使用的致谢 credit 对象——方便时可以添加，但并非强制要求。

但仍须遵守实际限制，且该服务的指令会引导模型避免违规：不得在未修改内容的情况下将其转售为实体产品；不得在其他图库或壁纸平台上重新分发；不得将其用于商标、徽标或企业名称；不得暗示人物或品牌为其背书；不得以负面或冒犯性的方式描绘可识别的人物。请参阅完整的 Pexels 许可 和该服务的 pexels://guides/usage 资源。每位用户均受其各自的 Pexels API 条款约束。

速率限制

Pexels 为每个 API 密钥执行统一的速率限制：

服务会读取 X-Ratelimit-Limit/X-Ratelimit-Remaining/X-Ratelimit-Reset，并在每个结果中以 rate_limit 返回这些值。额度耗尽时，Pexels 会返回标准的 429（不同于某些会将 403 用于此情况的 API），但 429 响应本身不包含速率限制标头，因此客户端会缓存上一次成功调用时的值，以报告准确的重置时间；一旦确认额度耗尽，就会停止后续请求，而不会继续发起必然失败的调用。对于暂时性的 429/5xx/网络错误，则会采用退避策略重试。

Pexels 文本的处理方式

照片/视频的替代文本、摄影师姓名以及合集标题/描述均来自 Pexels 贡献者——应将它们视为不可信的第三方数据，而非指令。服务仅将这些文本作为内容返回，不会将其置于任何受信任的位置；你的客户端/Agent 也应如此处理：可以显示这些文本，但不要执行其中可能包含的任何指令（这是一种防范间接提示词注入的措施）。Pexels 也没有安全搜索/内容过滤参数，因此请谨慎构造搜索查询。

隐私与安全

• 无遥测。 此服务不会收集任何信息，也不会向任何人回传数据。它只会使用你提供的密钥联系 api.pexels.com。没有分析或跟踪。
• 密钥安全。 你的 API 密钥仅从环境变量中读取，以原始 Authorization 标头发送（绝不会放在 URL 查询字符串中），并且会从所有错误输出和日志中打码，防止密钥泄露到粘贴的错误报告中。
• 如需报告漏洞，请参阅 SECURITY.md。

故障排除

• 启动时显示“Set PEXELS_API_KEY…”——缺少密钥环境变量或其值为空；请将其添加到客户端配置的 env 块中。
• Node 版本过旧——此服务需要 Node 20+。请检查 node --version。
• npx 版本过旧——使用 npx -y @hanoak/pexels-mcp-server@latest 强制获取最新版本，或通过 npx clear-npx-cache 清除缓存。
• 未显示工具——确认配置文件路径和 JSON 有效，然后完全退出并重新打开客户端。
• 429 / 速率限制——额度为每小时 200 次请求；请等待每小时重置（查看工具结果中的 rate_limit.resetEpoch），或申请提高额度。
• 401 Unauthorized——API 密钥有误；请从 Pexels API dashboard 重新复制密钥。
• pexels_list_my_collections 返回空结果——这是预期行为，除非拥有你的 API 密钥的 Pexels 账号已在 pexels.com 上创建合集；请参阅 常见问题。

常见问题

我需要付费的 Pexels 账号吗？ 不需要。Pexels API 免费——只需创建账号即可立即获取 API 密钥，无需审核或审批。

它会下载或重新托管图片/视频吗？ 不会。它会返回由 Pexels 托管的 URL（可直接使用热链接），绝不会重新托管内容或返回 Base64 数据块。

为什么 pexels_list_my_collections 返回空结果？ Pexels 不提供按对话登录的功能——此工具始终反映配置的 API 密钥所属 Pexels 账号的合集，而非聊天者的合集。除非该特定账号已在 pexels.com 上创建合集，否则结果为空。

它能在 Claude 之外使用吗？ 可以——这是一个标准的 stdio MCP 服务。Claude Code、Cursor、VS Code、Windsurf 和通用 stdio 的配置方法，请参阅客户端配置部分。

要求

• Node.js >= 20（Node 18 已结束生命周期）。
• Pexels API 密钥。

兼容性

路线图

详细内容请见 docs/ROADMAP.md。简而言之：v1 一次性涵盖所有已文档化的 Pexels API——不像其他一些图库 MCP 服务那样需要 OAuth 层来拆分出 v2。正在考虑的未来范围包括视频版本的结构化工具输出、在确实出现配额压力时添加短 TTL 的响应缓存，以及更多提示词/资源。

变更记录见 CHANGELOG.md；本项目遵循 语义化版本。

贡献

欢迎贡献——请参阅 CONTRIBUTING.md 和我们的 行为准则。其中介绍了本地设置、测试套件、如何使用 MCP Inspector 手动测试工具，以及版本管理/弃用政策。如需报告漏洞，请参阅 SECURITY.md。

联系方式与社区

由 Hanoak S 维护。获取帮助或提出功能建议，最快的方式是提交 issue——issue 公开可见、可搜索，也能帮助整个社区。

如果这个项目对你有帮助，欢迎在 GitHub 上点亮 ⭐——这有助于其他寻找 Pexels MCP 服务的人发现本项目。

许可证

MIT © Hanoak S。与 Pexels 无关联。