Pexels MCP Server

Pexels MCP 服务

一个 Model Context Protocol (MCP) 服务，可访问 Pexels API，让 AI 模型能够搜索和获取 Pexels 上的照片、视频和合集。

功能

• 按查询词、方向、尺寸和颜色搜索照片和视频
• 访问 Pexels 上的精选和热门内容
• 浏览 Pexels 合集
• 获取特定照片和视频的详细信息
• 通过工具或直接 URI 资源访问内容

要求

• Node.js 18 或更高版本
• Pexels API 密钥（可在 https://www.pexels.com/api/ 获取）

本地开发

1. 克隆仓库
2. 安装依赖项

   pnpm install
   

3. 构建项目

   pnpm build
   

4. 在开发模式下运行

   PEXELS_API_KEY=your_api_key pnpm dev
   

部署到 Smithery

此 MCP 服务已准备好部署到 Smithery。请按以下步骤操作：

1. 将服务添加到 Smithery，或认领现有服务
2. 前往 Deployments 选项卡（仅已通过身份验证的所有者可见）
3. 部署服务
4. 配置部署时，在配置设置中提供 Pexels API 密钥

API 用法

该服务提供以下工具：

照片工具

• searchPhotos：按查询词搜索照片（使用描述性关键词以获得相关结果，例如“Thai hotel reception”“red sports car driving”，不要只用“hotel”或“car”；可结合 orientation、size、color 和 locale 等参数来优化结果），并可选按方向、尺寸、颜色、区域设置（例如“en-US”“es-ES”）、页码和每页结果数筛选。返回包括照片 ID 和 URL 在内的元数据，以及当前 API 速率限制状态。
• downloadPhoto：按照片 ID 和所需尺寸获取特定照片（可选，默认为“original”）。可用尺寸：“original”“large2x”“large”“medium”“small”“portrait”“landscape”“tiny”。返回所请求图片尺寸的直接下载链接、建议文件名（包含尺寸）和署名信息。AI 客户端应使用可用的本地工具（如 curl 或 PowerShell 的 Invoke-WebRequest），通过提供的链接下载照片。
• getCuratedPhotos：从 Pexels 获取一组精选照片，可选择分页。
• getPhoto：按照片 ID 获取特定照片的详细信息。

视频工具

• searchVideos：按查询词搜索视频（使用描述性关键词以获得相关结果，例如“drone footage beach sunset”“time lapse city traffic”，不要只用“beach”或“city”；可结合 orientation 和 size 等参数来优化结果），并可选按方向、尺寸、区域设置（例如“en-US”“es-ES”）、页码和每页结果数筛选。返回包括视频 ID 和 URL 在内的元数据，以及当前 API 速率限制状态。
• getPopularVideos：从 Pexels 获取热门视频列表，并可选按尺寸、时长、页码和每页结果数筛选。
• getVideo：按视频 ID 获取特定视频的详细信息。
• downloadVideo：按视频 ID 和首选画质（hd/sd）获取特定视频。返回直接下载链接、建议文件名和署名信息。AI 客户端应使用可用的本地工具（如 curl 或 PowerShell 的 Invoke-WebRequest），通过提供的链接下载视频。

合集工具

• getFeaturedCollections：从 Pexels 获取精选合集列表，可选择分页。
• getMyCollections：（代码中已注释）需要 OAuth 2.0 身份验证，此服务不支持。
• getCollectionMedia：按合集 ID 获取特定合集中的媒体项目（照片或视频），并可选按类型、排序方式、页码和每页结果数筛选。

资源

服务器提供以下可通过 URI 访问的资源：

• pexels-photo://{id}：按 ID 访问特定照片
• pexels-video://{id}：按 ID 访问特定视频
• pexels-collection://{id}：按 ID 访问特定合集

错误处理

服务器会尝试针对常见问题提供有用的错误消息，例如 API 密钥无效、请求速率受限或资源缺失。成功响应还会在输出中包含当前 Pexels API 的请求速率限制状态（剩余请求数、重置时间）。

署名要求

使用 Pexels API 时，必须遵守其署名要求：

• 始终显示醒目的 Pexels 链接（例如“照片由 Pexels 提供”）
• 始终注明摄影师（例如“照片由 John Doe 在 Pexels 拍摄”）

许可证

ISC