MCP Pexels

mcp-pexels — 面向 Claude、Cursor 和其他 AI Agent 的 Pexels MCP 服务

一个 Model Context Protocol 服务，将 Pexels API——免费图库照片、视频和精选合集——作为 MCP 工具提供，让任何兼容的 AI 客户端（Claude Desktop、Claude Code、Cursor、Cline、Continue 等）都能直接在聊天中调用。

📦 npm： mcp-pexels · 🏷 最新版本： v1.0.0 · 💻 源码： developer-ishan/mcp-pexels

照片和视频由 Pexels 提供。

即插即用配置

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

将其粘贴到 MCP 客户端的配置中，重启后即可使用九个 pexels_* 工具。前往 https://www.pexels.com/api/ 免费获取密钥。

---

目录

• 你可以用它构建什么？
• 功能 — 九个工具
• 连接到 MCP 客户端
  • Claude Desktop
  • Claude Code
  • Cursor
  • Cline (VS Code)
  • Continue.dev
  • 通用 / 其他客户端
• 提示词示例
• 对比
• 常见问题
• 要求
• 开发
• 发布
• 贡献
• 署名与许可证

---

你可以用它构建什么？

将 mcp-pexels 连接到 AI 客户端后，Agent 就能将免版税照片和视频直接引入工作流。以下是一些具体用途：

• 幻灯片和文档配图 — “帮我找一张日落时分的山景照片，用于第 3 张幻灯片” → Agent 搜索 Pexels、挑选一张并将其嵌入。
• 博客文章 / 社交媒体内容撰写 — “为一篇关于远程办公的文章推荐三个缩略图选项” → 返回三个附有摄影师署名的 Pexels URL。
• 视频剪辑背景素材调研 — “展示时长不足 30 秒的热门 4K 无人机素材” → 使用带有尺寸和时长筛选条件的 pexels_popular_videos。
• 情绪板 — “帮我制作一份暖色调咖啡馆照片情绪板” → 使用 color: "orange" 搜索。
• 编码 Agent — 生成包含逼真占位图片而非 lorem-pixel 方框的 CSS/HTML。
• 精选合集 — 将特定的 Pexels 合集（例如 Pexels 上标记的公司自有照片）导入 Agent 上下文。

由于每个响应都包含 _rateLimit 对象，Agent 可以自行控制请求频率，并遵守 Pexels 免费套餐配额（每小时 200 次请求，每月 20 000 次）。

---

功能 — 九个工具

领域	工具	功能说明
照片	pexels_search_photos	根据查询搜索照片，可按方向、尺寸、颜色和区域设置筛选条件。
照片	pexels_curated_photos	获取 Pexels 团队实时精选的照片流。
照片	pexels_get_photo	根据数字 ID 获取单张照片。
视频	pexels_search_videos	根据查询搜索视频，可按方向、尺寸和区域设置筛选条件。
视频	pexels_popular_videos	获取热门视频，可选设置宽度、高度和时长限制。
视频	pexels_get_video	根据数字 ID 获取单个视频。
合集	pexels_featured_collections	列出 Pexels 精选合集。
合集	pexels_my_collections	列出已认证用户自己的合集。
合集	pexels_collection_media	获取指定合集中的照片和视频。

每个工具的响应都是原始 Pexels JSON，并合并了顶层 _rateLimit 字段，其中包含 limit、remaining 和 reset（UNIX 时间戳）。

请参阅 docs/tools/，了解各工具的参数表和示例负载。

---

连接到 MCP 客户端

以下所有路径均使用 npx -y mcp-pexels — 无需全局安装。请将 your_key_here 替换为有效的 Pexels API 密钥。

Claude Desktop

选项 1 — 一键安装 .mcpb（推荐）。 从 Releases 页面下载最新的 mcp-pexels-*.mcpb，双击文件，在 Claude Desktop 提示时粘贴你的 Pexels API 密钥，然后点击 Install。

选项 2 — 手动配置 JSON。 编辑 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" }
    }
  }
}

重启 Claude Desktop。

Claude Code

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

也可以直接编辑 ~/.claude.json，并添加与上文相同的 mcpServers 配置块。

Cursor

编辑 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）：

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

Cline（VS Code）

打开 Cline 扩展设置 → MCP Servers → Edit Settings。添加：

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

Continue.dev

在 ~/.continue/config.json 中：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "mcp-pexels"],
          "env": { "PEXELS_API_KEY": "your_key_here" }
        }
      }
    ]
  }
}

通用 / 其他客户端

如果你的客户端支持 stdio MCP 服务，只需配置 command、args 和 env。使用与上文 Cursor / Claude Desktop 相同的格式。用于检查器 / 调试：

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

这会打开一个浏览器界面，你可以在其中交互式调用每个工具。

---

示例提示词

连接后，可以试试这些提示词：

• “帮我找五张黄金时段的山脉横向照片。确保分辨率至少达到全高清。”
• “帮我找一些 Pexels 上时长不到 15 秒、分辨率达到 1080p 或更高的城市交通热门视频。”
• “获取 ID 为 2014422 的照片，并告诉我摄影师是谁。”
• “列出 Pexels 精选合集 — 我想找一个可以浏览烹饪照片的合集。”
• “搜索竖屏的‘forest’视频；帮我选出画质最高的高清文件。”
• “给我看看以橙色调为主、适合作为秋季主题新闻简报标题图的 Pexels 照片。”

Agent 会选择合适的工具，发送正确的参数，并在回答中附上摄影师 / 摄像师署名。

---

对比

	mcp-pexels	Pexels 原始 REST API	仅支持图片的通用 MCP 服务
照片	✅	✅	不定
视频	✅	✅	通常 ❌
收藏集	✅	✅	❌
向 Agent 暴露速率限制响应头	✅	❌（原始响应头，Agent 必须解析）	❌
经 Zod 验证的输入	✅	❌	不定
可通过 npx 安装，无需配置	✅	❌	不定
类型安全的 TS 源码	✅	不适用	不定
MIT 许可	✅	不适用	不定

如果你只需要照片，而且已经接入了通用图片 MCP 服务，那可能就够用了。如果你需要一流的视频和收藏集支持，以及速率限制感知功能，那么这个项目就是为此量身打造的。

---

常见问题

如何获取 Pexels API 密钥？

前往 https://www.pexels.com/api/ 注册，即可立即获取密钥；免费套餐允许每小时 200 次请求，每月 20 000 次请求。

这需要付费吗？

不需要。Pexels API 免费，npm 包免费（MIT），而且 mcp-pexels 本身不会调用任何付费服务。

可以离线使用吗？

不可以。该服务只是 Pexels HTTPS API 的轻量封装，需要网络连接。

我可以将 Pexels 内容用于商业用途吗？

可以，具体遵循 Pexels 许可；但你必须注明平台和（如果可能）摄影师。请参阅署名与许可。

它能与 Claude.ai（浏览器）配合使用吗？

Claude.ai 的 Web 产品目前还不支持 stdio MCP 服务，只支持 Claude Desktop、Claude Code 和 API。Anthropic 正在逐步推出浏览器 MCP 支持，因此这一情况应该会有所改变。

有托管版 / SaaS 版本吗？

没有。通过 npx 在本地运行即可。由于 Pexels API 密钥是按用户分配的，托管共享实例并不合理。

如何更新到较新版本？

npx 总是获取最新发布版本。如果你已全局安装，请运行 npm update -g mcp-pexels。

可以添加更多 Pexels 端点吗？

Pexels API 的全部接口都已实现（截至 Pexels API v1，共 9/9 个端点）。新端点将通过 PR 添加，请参阅贡献指南。

它能与 @modelcontextprotocol/inspector 配合使用吗？

可以：

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

如何处理速率限制？

每个工具响应都包含一个 _rateLimit 对象，其中有 limit、remaining 和 reset（UNIX 时间戳）。Agent 可以读取这些信息并自行限制请求速率。如果 Pexels 返回 429，服务会将其显示为 PexelsApiError，让 Agent 获知失败情况。

我的 API 密钥会发送到哪里？

它从本地进程的 PEXELS_API_KEY 环境变量中读取。除了通过 Authorization 请求头发送到 api.pexels.com，密钥不会离开你的设备。不会记录任何内容。

---

要求

• Node.js ≥ 20（使用原生 fetch 和 --env-file）
• 免费的 Pexels API 密钥——在此申请

---

开发

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

项目结构

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

测试方法

测试通过 makeMockClient(responses) 返回的 vi.fn() fetchImpl 构造 PexelsClient。不会执行真实 HTTP 请求。每个工具都会针对以下情况进行测试：

1. 正常路径——URL 序列化和 Authorization 请求头。
2. 错误映射——非 2xx 响应 → 带有 status 和 body 的 PexelsApiError。
3. Zod 验证——必需参数、枚举成员、整数范围。

---

发布

此仓库使用基于标签的发布工作流（.github/workflows/release.yml）：

1. 更新版本：npm version patch（或 minor / major）——创建提交和标签。
2. 推送：git push && git push --tags。
3. 工作流会运行测试、构建、使用仓库密钥 NPM_TOKEN 并通过 provenance 发布到 npm、通过 npm run pack:mcpb 构建 .mcpb bundle，并创建包含自动生成说明的 GitHub release，其中会将 bundle 作为可下载资源。

版本历史请参阅 CHANGELOG.md。

---

贡献

欢迎提交问题和拉取请求。开发工作流请参阅 CONTRIBUTING.md，私下报告漏洞请参阅 SECURITY.md。

如果你在工具或产品中集成了 mcp-pexels，请提交 PR，将其添加到 CONTRIBUTING.md 中的“Used by”列表。

已收录于 / 提交至

• Smithery — 通过 smithery.yaml 自动发现。
• mcp.so — 社区目录。
• awesome-mcp-servers — 精选的 GitHub 列表。
• modelcontextprotocol/servers — Anthropic 的官方目录。

提交指南请参阅 docs/MARKETPLACES.md。

---

署名与许可

使用 Pexels 内容时，请遵守 Pexels API 指南：

• 显著展示指向 Pexels 的链接，例如 “照片由 Pexels 提供”。
• 尽可能注明摄影师／摄像师，例如 “照片由 John Doe 拍摄，来自 Pexels”。

mcp-pexels 软件包本身采用 MIT 许可证发布。