mcp-server-pexels

Un servidor MCP para la búsqueda de fotos y vídeos de stock de Pexels. Optimizado para LLMs.

Pexels proporciona fotos y vídeos de stock gratuitos.

Características

• Búsqueda de fotos — Busca fotos con filtros (consulta, orientación, tamaño, color, idioma)

• Búsqueda de vídeos — Busca vídeos, selecciona automáticamente el .mp4 en HD más cercano a 1920x1080

• Obtener detalles — Recupera los metadatos completos de una foto/vídeo por ID

• Caché inteligente — TTL de 10 min para búsquedas, 60 min para consultas por ID

• Gestión de errores — Fallos controlados con mensajes útiles (según las mejores prácticas de MCP)

• Atribución — Créditos obligatorios del fotógrafo en cada resultado

Requisitos previos

• Node.js v20+

• Clave API de Pexels (gratuita en pexels.com/api)

Inicio rápido (2 minutos)

1. Obtén una clave API

Regístrate en pexels.com/api — es gratis, no requiere tarjeta de crédito.

2. Construye el servidor

npm install && npm run build

3. Añádelo a Claude Desktop

Abre ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) o %APPDATA%\Claude\claude_desktop_config.json (Windows), y añade:

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

Nota para Windows: Usa la ruta completa de node.exe o añade Node al PATH. Las barras inclinadas hacia adelante funcionan en Windows.

4. Reinicia Claude Desktop

El servidor ahora está disponible como pexels_search_photos, pexels_search_videos y pexels_get_details.

Configuración

Añade a tu .mcp.json o claude_desktop_config.json:

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

Entorno

Establece PEXELS_API_KEY en tu entorno. Para desarrollo local, crea un archivo .env:

PEXELS_API_KEY=your_pexels_api_key

Desarrollo

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

Herramientas

Arquitectura

• src/index.ts — Punto de entrada, configuración del servidor MCP

• src/tools/ — Implementaciones de herramientas

• src/shared/ — Caché, cliente API, errores, tipos, selector de vídeo

• src/utils/ — Esquemas de validación Zod

Decisiones de ingeniería

Compatibilidad

Probado con @modelcontextprotocol/sdk v1.29+ a través de StdioClientTransport. El conjunto de pruebas de integración genera el servidor compilado y valida cada llamada a la herramienta contra CallToolResultSchema y ContentBlockSchema del SDK.

Se añade un bloque JSON estructurado como último elemento de contenido en cada respuesta exitosa, que contiene datos tipados (id, tipo, nombre del creador, dimensiones, URLs). Los clientes intermedios y los marcos de trabajo de agentes pueden analizar este bloque directamente en lugar de analizar el texto markdown mediante expresiones regulares.

Mejoras futuras

• Telemetría de ejecución de herramientas — Añadir registro estructurado para aciertos/fallos de caché, tiempo de ejecución de consultas y tasas de error. Esto ayuda a solucionar problemas de agentes de IA en producción y demuestra las mejores prácticas de observabilidad.

• Punto final de métricas — Exponer contadores (solicitudes atendidas, tasa de aciertos de caché, cuota de API restante) para monitorización.

• Configuración de TTL personalizada — Permitir a los usuarios ajustar el TTL de la caché mediante variables de entorno.

Contribuciones de la comunidad

• ¡Son bienvenidas! 🌟

Licencia

Proyecto comunitario no oficial. No afiliado a Pexels.