内容
# mcp-pexels — Pexels MCP 服务器，用于 Claude、Cursor 及其他 AI 代理
[](https://www.npmjs.com/package/mcp-pexels)
[](https://www.npmjs.com/package/mcp-pexels)
[](https://github.com/developer-ishan/mcp-pexels/actions/workflows/ci.yml)
[](./LICENSE)
[](#要求)
[](https://modelcontextprotocol.io)
**一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，暴露 [Pexels API](https://www.pexels.com/api/) — 免费的库存照片、视频和精选收藏 — 作为 MCP 工具，任何兼容的 AI 客户端（Claude Desktop、Claude Code、Cursor、Cline、Continue 等）可以直接从聊天中调用。**
📦 **npm:** [mcp-pexels](https://www.npmjs.com/package/mcp-pexels) · 🏷 **最新版本：** [v1.0.0](https://github.com/developer-ishan/mcp-pexels/releases/tag/v1.0.0) · 💻 **源码：** [developer-ishan/mcp-pexels](https://github.com/developer-ishan/mcp-pexels)
> 照片和视频由 [Pexels](https://www.pexels.com) 提供。
## 直接配置
```json
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
```
粘贴到您的 MCP 客户端配置中，重启后，九个 `pexels_*` 工具即可使用。在 <https://www.pexels.com/api/> 获取免费密钥。
---
## 目录
- [您可以构建什么](#您可以构建什么)
- [功能 — 九个工具](#功能——九个工具)
- [连接到您的 MCP 客户端](#连接到您的mcp客户端)
- [Claude Desktop](#claude-desktop)
- [Claude Code](#claude-code)
- [Cursor](#cursor)
- [Cline（VS Code）](#cline-vs-code)
- [Continue.dev](#continuedev)
- [通用/其他客户端](#通用其他客户端)
- [示例提示](#示例提示)
- [比较](#比较)
- [FAQ](#faq)
- [要求](#要求)
- [开发](#开发)
- [发布](#发布)
- [贡献](#贡献)
- [归属和许可证](#归属和许可证)
---
## 您可以构建什么
一旦 `mcp-pexels` 连接到 AI 客户端，代理就可以直接拉取免版税的照片和视频到其工作流中。一些具体的用途：
- **幻灯片和文档插图** — “给我找一张日落时分的山景照片，用于幻灯片 3” → 代理搜索 Pexels，选择一张并嵌入。
- **博客文章/社交媒体草稿** — “为一篇关于远程工作的文章建议三个缩略图选项” → 返回三个 Pexels URL 和摄影师信用。
- **视频编辑的背景研究** — “给我展示 30 秒以内、4K 的热门无人机视频” → 使用 `pexels_popular_videos`，带有尺寸和时长过滤器。
- **情绪板** — “给我创建一个温暖色调的咖啡店照片情绪板” → 使用 `color: "orange"` 搜索。
- **编码代理** — 使用真实的占位图像生成 CSS/HTML，而不是 `lorem-pixel` 框。
- **精选收藏** — 将特定的 Pexels 收藏（例如 Pexels 上标记的公司所有照片）拉取到代理的上下文中。
由于每个响应都包含一个 `_rateLimit` 对象，代理可以自我限制并尊重 Pexels 免费层配额（200 请求/小时，20,000 请求/月）。
---
## 功能 — 九个工具
| 领域 | 工具 | 功能 |
|---|---|---|
| 照片 | [`pexels_search_photos`](./docs/tools/pexels_search_photos.md) | 按查询搜索照片，带有方向/尺寸/颜色/地区过滤器。 |
| 照片 | [`pexels_curated_photos`](./docs/tools/pexels_curated_photos.md) | 获取 Pexels 团队的实时精选照片动态。 |
| 照片 | [`pexels_get_photo`](./docs/tools/pexels_get_photo.md) | 通过其数字 ID 检索单个照片。 |
| 视频 | [`pexels_search_videos`](./docs/tools/pexels_search_videos.md) | 按查询搜索视频，带有方向/尺寸/地区过滤器。 |
| 视频 | [`pexels_popular_videos`](./docs/tools/pexels_popular_videos.md) | 获取热门视频，带有可选的宽度/高度/时长约束。 |
| 视频 | [`pexels_get_video`](./docs/tools/pexels_get_video.md) | 通过其数字 ID 检索单个视频。 |
| 收藏 | [`pexels_featured_collections`](./docs/tools/pexels_featured_collections.md) | 列出 Pexels 精选收藏。 |
| 收藏 | [`pexels_my_collections`](./docs/tools/pexels_my_collections.md) | 列出经过身份验证的用户自己的收藏。 |
| 收藏 | [`pexels_collection_media`](./docs/tools/pexels_collection_media.md) | 检索特定收藏中的照片和视频。 |
每个工具响应都是原始 Pexels JSON 与顶级 `_rateLimit` 字段的合并，暴露 `limit`、`remaining` 和 `reset`（UNIX 时间戳）。
参见 [`docs/tools/`](docs/tools/) 获取每个工具的参数表和示例有效负载。
---
## 连接到您的 MCP 客户端
以下所有路径都使用 `npx -y mcp-pexels` — 无需全局安装。替换 `your_key_here` 为实际的 Pexels API 密钥。
### Claude Desktop
**选项 1 — 一键 `.mcpb` 安装（推荐）。** 从 [Releases 页面](https://github.com/developer-ishan/mcp-pexels/releases/latest) 下载最新的 `mcp-pexels-*.mcpb`，双击文件，粘贴您的 Pexels API 密钥，然后单击安装。
**选项 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`
```json
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
```
重启 Claude Desktop。
### Claude Code
```bash
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`（按项目）：
```json
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
```
### Cline（VS Code）
打开 Cline 扩展设置 → **MCP 服务器** → **编辑设置**。添加：
```json
{
"mcpServers": {
"pexels": {
"command": "npx",
"args": ["-y", "mcp-pexels"],
"env": { "PEXELS_API_KEY": "your_key_here" }
}
}
}
```
### Continue.dev
在 `~/.continue/config.json` 中：
```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 上相同的形状进行。对于检查/调试：
```bash
export PEXELS_API_KEY=your_key_here
npx -y @modelcontextprotocol/inspector npx -y mcp-pexels
```
这会打开一个浏览器 UI，您可以在其中交互式地调用每个工具。
---
## 示例提示
连接后，尝试以下提示：
- *"给我找五张日落时分的山景照片。确保它们至少是全高清的。*
- *"给我 Pexels 中小于 15 秒、1080p 或更高、城市交通的热门视频。*
- *"拉取照片 ID 2014422 并告诉我摄影师。*
- *"列出精选的 Pexels 收藏 — 我想找一个可以浏览的烹饪照片收藏。*
- *"搜索‘森林’的视频，纵向方向；为我选择最高质量的 HD 文件。*
- *"给我展示 Pexels 中以橙色为主的照片，适合秋季主题新闻稿标题。*
代理将选择适当的工具，发送正确的参数，并将摄影师/摄像师的信用作为其答案的一部分。
---
## 比较
| | mcp-pexels | 原始 Pexels REST API | 仅限图片的通用 MCP 服务器 |
|---|---|---|---|
| 照片 | ✅ | ✅ | 变化 |
| 视频 | ✅ | ✅ | 通常 ❌ |
| 收藏 | ✅ | ✅ | ❌ |
| 速率限制标头暴露给代理 | ✅ | ❌（原始标头，代理必须解析） | ❌ |
| Zod 验证输入 | ✅ | ❌ | 变化 |
| `npx` 可安装，零配置 | ✅ | ❌ | 变化 |
| 类型安全的 TS 源 | ✅ | n/a | 变化 |
| MIT 许可 | ✅ | n/a | 变化 |
如果您只需要照片，并且已经有一个通用的图片 MCP 服务器，可以使用该服务器。如果您需要一流的视频和收藏支持，并具有速率限制感知，此功能专门为此而构建。
---
## FAQ
### 如何获取 Pexels API 密钥？
在 <https://www.pexels.com/api/> 注册 — 密钥立即发放，免费层允许 **200 请求/小时** 和 **20,000 请求/月**。
### 这需要付费吗？
不。Pexels API 是免费的，npm 包是免费的（MIT），`mcp-pexels` 本身不调用任何付费服务。
### 这会在离线时工作吗？
不 — 服务器是 Pexels HTTPS API 的薄包装，需要网络访问。
### 我可以将 Pexels 内容用于商业用途吗？
是的，根据 Pexels 许可，但您必须注明平台和（如果可能）摄影师。参见 [Attribution](#attribution--license)。
### 它与 Claude.ai（浏览器）一起工作吗？
Claude.ai 的网页产品尚不支持 stdio MCP 服务器 — 只有 Claude Desktop、Claude Code 和 API 支持。Anthropic 正在推出浏览器 MCP 支持，因此这应该会改变。
### 有托管/SaaS 版本吗？
不。通过 `npx` 运行它。因为 Pexels API 密钥是每个用户独有的，所以托管共享实例没有意义。
### 如何更新到新版本？
`npx` 始终获取最新发布的版本。如果您已全局安装，请运行 `npm update -g mcp-pexels`。
### 我可以添加更多 Pexels 端点吗？
Pexels API 接口已完全实现（9/9 端点，截至 Pexels API v1）。将通过 PR 添加新端点 — 参见 [Contributing](#contributing)。
### 它与 `@modelcontextprotocol/inspector` 一起工作吗？
是的：
```bash
export PEXELS_API_KEY=your_key_here
npx -y @modelcontextprotocol/inspector npx -y mcp-pexels
```
### 速率限制如何处理？
每个工具响应都包含一个 `_rateLimit` 对象，包含 `limit`、`remaining` 和 `reset`（UNIX 时间戳）。代理可以读取此内容并自我限制。如果 Pexels 返回 429，服务器将其作为 `PexelsApiError` 提出，以便代理看到失败。
### 我的 API 密钥去哪了？
它从本地进程的 `PEXELS_API_KEY` 环境变量中读取。除 `Authorization` 标头发送到 `api.pexels.com` 外，它不会离开您的机器。不会记录任何内容。
---
## 要求
- Node.js **≥ 20**（使用原生 `fetch` 和 `--env-file`）
- 一个免费的 Pexels API 密钥 — [在此请求一个](https://www.pexels.com/api/)
---
## 开发
```bash
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 个模拟 vitest 测试用例，无网络
npm run build # tsc → dist/
npm run dev # tsx 监视
npm run test:watch # vitest 监视模式
npm start # node --env-file=.env dist/index.js
```
### 项目布局
```
src/
├── index.ts # MCP 服务器入口点（stdio）
├── http/
│ ├── client.ts # PexelsClient（可注入测试的 fetch）
│ └── types.ts # PexelsApiError, RateLimit, PexelsResponse
├── tools/
│ ├── index.ts # 组合三个领域工厂
│ ├── photos.ts # 3 个照片工具
│ ├── videos.ts # 3 个视频工具
│ └── collections.ts # 3 个收藏工具
└── types/
├── tool.ts # defineTool 帮助程序 + ToolDefinition
├── photos.ts
├── videos.ts
└── collections.ts
tests/
├── helpers/mockClient.ts # makeMockClient() — 假 fetch 通过 vitest 模拟
├── photos.test.ts # 17 个测试用例
├── videos.test.ts # 13 个测试用例
└── collections.test.ts # 12 个测试用例
```
### 测试方法
测试构造一个带有 `vi.fn()` `fetchImpl` 的 `PexelsClient`，由 `makeMockClient(responses)` 返回。不会执行实际的 HTTP。每个工具都会进行：
1. **快乐路径** — URL 序列化 和 `Authorization` 标头。
2. **错误映射** — 非 2xx → `PexelsApiError` 和 `status` 和 `body`。
3. **Zod 验证** — 必需参数、枚举成员、整数边界。
---
## 发布
此仓库使用标签驱动的发布工作流（`.github/workflows/release.yml`）：
1. 升级版本：`npm version patch`（或 `minor` / `major`）— 创建提交和标签。
2. 推送：`git push && git push --tags`。
3. 工作流运行测试、构建、使用 `NPM_TOKEN` 仓库秘密发布到 npm、构建 **`.mcpb` 包**，并使用自动生成的笔记创建 GitHub 发布，包括 bundle 作为可下载的资产。
参见 `./CHANGELOG.md` 获取版本历史记录。
---
## 贡献
欢迎提出问题和拉取请求。参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 获取开发工作流和 [`SECURITY.md`](./SECURITY.md) 私密报告漏洞。
如果您在工具或产品中使用 `mcp-pexels`，请打开一个 PR 将其添加到 [“Used by” 列表](./CONTRIBUTING.md) 中。
### 已列出/提交到
- **[Smithery](https://smithery.ai/)** — 通过 [`smithery.yaml`](./smithery.yaml) 自动发现。
- **[mcp.so](https://mcp.so)** — 社区目录。
- **[awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)** — 整理的 GitHub 列表。
- **[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)** — Anthropic 的官方目录。
参见 [`docs/MARKETPLACES.md`](./docs/MARKETPLACES.md) 获取提交的秘诀。
---
## 归属和许可证
使用 Pexels 内容时，请遵循 [Pexels API 指南](https://www.pexels.com/api/documentation/#guidelines)：
- 显示指向 Pexels 的显眼链接 — 例如 *"Photos provided by Pexels"*。
- 在可能的情况下提供摄影师/摄像师的信用 — 例如 *"Photo by John Doe on Pexels"*。
`mcp-pexels` 包本身在 [MIT License](./LICENSE) 下发布。
<|end_header_id|>
<|end_header_id|>
请注意，我已将所有英文的技术名词和代码保留下来，只翻译了文档内容。如果您有任何进一步的要求，请告诉我。
