mcp-server-pexels

一个用于 Pexels 库存照片和视频搜索的 MCP 服务器。针对 LLM 进行了优化。

Pexels 提供免费的库存照片和视频。

功能

• 照片搜索 — 使用过滤器（查询、方向、尺寸、颜色、区域设置）搜索照片

• 视频搜索 — 搜索视频，自动选择最接近 1920x1080 的高清 .mp4

• 获取详情 — 通过 ID 获取照片/视频的完整元数据

• 智能缓存 — 搜索结果 10 分钟 TTL，ID 查询 60 分钟 TTL

• 错误处理 — 优雅地处理失败并提供有用的消息（遵循 MCP 最佳实践）

• 署名 — 每个结果中必须包含摄影师署名

先决条件

• Node.js v20+

• Pexels API 密钥（在 pexels.com/api 免费获取）

快速入门（2 分钟）

1. 获取 API 密钥

在 pexels.com/api 注册 — 免费，无需信用卡。

2. 构建服务器

npm install && npm run build

3. 添加到 Claude Desktop

打开 ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)，添加：

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-pexels/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_PEXELS_API_KEY"
      }
    }
  }
}

Windows 注意： 使用 node.exe 的完整路径或将 Node 添加到 PATH。路径中的正斜杠在 Windows 上同样有效。

4. 重启 Claude Desktop

服务器现在可用，工具包括 pexels_search_photos、pexels_search_videos 和 pexels_get_details。

配置

添加到您的 .mcp.json 或 claude_desktop_config.json：

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

环境

在您的环境中设置 PEXELS_API_KEY。对于本地开发，创建一个 .env 文件：

PEXELS_API_KEY=your_pexels_api_key

开发

npm run dev      # watch mode
npm run inspector # MCP Inspector
npm test          # run tests

工具

架构

• src/index.ts — 入口点，MCP 服务器设置

• src/tools/ — 工具实现

• src/shared/ — 缓存、API 客户端、错误、类型、视频选择器

• src/utils/ — Zod 验证模式

工程决策

兼容性

通过 StdioClientTransport 在 @modelcontextprotocol/sdk v1.29+ 上进行了测试。集成测试套件会启动构建好的服务器，并根据 SDK 的 CallToolResultSchema 和 ContentBlockSchema 验证每个工具调用。

结构化的 JSON 块作为每个成功响应的最后一个内容元素附加，包含类型化数据（id、kind、creatorName、dimensions、URLs）。下游客户端和代理框架可以直接解析此块，而不是通过正则表达式解析 markdown 文本。

未来改进

• 工具执行遥测 — 添加用于缓存命中/未命中、查询执行时间和错误率的结构化日志记录。这支持生产中 AI 代理的故障排除，并展示了可观测性最佳实践。

• 指标端点 — 公开计数器（已处理请求、缓存命中率、剩余 API 配额）以进行监控。

• 自定义 TTL 配置 — 允许用户通过环境变量调整缓存 TTL。

社区贡献

• 欢迎提交！🌟

许可证

非官方社区项目。与 Pexels 无关联。