pexels-mcp-server

pexels-mcp-server

Un servidor Model Context Protocol (MCP) listo para producción para la API de Pexels. Proporciona a los asistentes de IA — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf y cualquier cliente MCP — herramientas para buscar y obtener fotos, vídeos y colecciones de Pexels, cubriendo todos los endpoints que documenta la API de Pexels.

[!IMPORTANT] Proyecto no oficial. No está afiliado, respaldado ni patrocinado por Pexels. «Pexels» es una marca comercial de su respectivo propietario. Lo usas con tu propia cuenta de la API de Pexels y eres responsable de cumplir con la Licencia de Pexels.

Tabla de contenidos

• Características
• Inicio rápido
• Ejemplo de interacción
• Configuración
• Herramientas
  • Referencia de herramientas
  • Forma de la salida
  • Recursos y prompts
• Ejemplos de prompts
• Licencia y cumplimiento
• Límites de velocidad
• Manejo del texto de Pexels
• Privacidad y seguridad
• Solución de problemas
• Preguntas frecuentes
• Requisitos
• Compatibilidad
• Hoja de ruta
• Contribuciones
• Contacto y comunidad
• Licencia

Características

• 9 herramientas que cubren todos los endpoints documentados de Pexels — fotos (búsqueda, seleccionadas, obtener), vídeos (búsqueda, populares, obtener) y colecciones (destacadas, medios, mías). Pexels tiene un único nivel de autenticación por clave de API y no tiene endpoints de escritura, por lo que no existe un «solo lectura v1» parcial: esta es toda la superficie.
• Consciente de la licencia por diseño — Pexels no exige atribución, pero cada foto sigue devolviendo un credit de cortesía listo para usar (texto + HTML), y las instrucciones del servidor guían al modelo en torno a las restricciones de licencia que sí aplican (no revender contenido sin modificar, no redistribuir a otras plataformas de stock, no usar marcas comerciales/logotipos, no implicar respaldo).
• URLs reales de imágenes y vídeos — cada foto devuelve las URLs de src con tamaños predefinidos de Pexels (original/large2x/large/medium/small/portrait/landscape/tiny); cada vídeo devuelve sus versiones video_files (recortadas a las pocas de mayor resolución en resultados de lista, completas en una consulta de un solo elemento).
• Salida eficiente en tokens — las respuestas completas de Pexels se recortan a una forma compacta (URLs + metadatos como texto, nunca blobs base64) para mantener pequeño el contexto del modelo.
• Robusto — fallos tipados devueltos como resultados MCP isError de los que el modelo puede recuperarse, además de reintentos/backoff, tiempos de espera y cortocircuito de cuota consciente de los límites de velocidad (Pexels omite sus cabeceras de límite de velocidad en un 429, por lo que el cliente almacena en caché la última hora de reinicio conocida en lugar de adivinar).
• Seguro — redacción de la clave de API en toda la salida de errores y orientación sobre el manejo de texto no confiable para la defensa contra inyección indirecta de prompts.
• Ligero y moderno — ESM, Node 20+, instalación cero mediante npx, sin telemetría.

Inicio rápido

1. Obtén una clave de API de Pexels

Crea una cuenta gratuita en pexels.com/api y recibirás una clave de API al instante: sin revisión de la aplicación, sin espera de aprobación.

2. Añade el servidor a tu cliente MCP

Claude Desktop — edita claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "@hanoak/pexels-mcp-server"],
      "env": {
        "PEXELS_API_KEY": "your_api_key"
      }
    }
  }
}

Reinicia el cliente. Consulta Configuración para ver todas las variables admitidas.

claude mcp add pexels \
  --env PEXELS_API_KEY=your_api_key \
  -- npx -y @hanoak/pexels-mcp-server

{
  "servers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "@hanoak/pexels-mcp-server"],
      "env": {
        "PEXELS_API_KEY": "your_api_key"
      }
    }
  }
}

PEXELS_API_KEY=your_api_key npx -y @hanoak/pexels-mcp-server

3. Pruébalo

Reinicia tu cliente y pregunta:

"Encuéntrame una foto de montañas en Pexels."

Ejemplo de interacción

Un flujo típico: el modelo llama a pexels_search_photos, elige un resultado y presenta la imagen con su crédito de cortesía.

Tú: Encuentra una foto de paisaje de un bosque de pinos con niebla.

Asistente: (llama a pexels_search_photos con query: "foggy pine forest", orientation: "landscape", elige el mejor resultado) Aquí tienes una gran coincidencia: foto de Jane Doe en Pexels, junto con la URL de la imagen y una línea de crédito lista para usar.

Cada herramienta devuelve una carga útil JSON compacta. Esta es la forma de un resultado de foto individual (valores ilustrativos):

{
  "photo": {
    "id": 1103970,
    "alt": "Photography of Trees at Foggy Forest",
    "width": 4000,
    "height": 2667,
    "avg_color": "#3E361F",
    "url": "https://www.pexels.com/photo/photography-of-trees-at-foggy-forest-1103970/",
    "src": {
      "original": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg",
      "large2x": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=650&w=940",
      "large": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=650&w=940",
      "medium": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=350",
      "small": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&h=130",
      "portrait": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=1200&w=800",
      "landscape": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=627&w=1200",
      "tiny": "https://images.pexels.com/photos/1103970/pexels-photo-1103970.jpeg?auto=compress&cs=tinysrgb&dpr=1&fit=crop&h=200&w=280"
    },
    "photographer": {
      "name": "Jane Doe",
      "url": "https://www.pexels.com/@janedoe",
      "id": 42
    },
    "credit": {
      "text": "Photo by Jane Doe on Pexels",
      "html": "Photo by <a href=\"https://www.pexels.com/@janedoe\">Jane Doe</a> on <a href=\"https://www.pexels.com\">Pexels</a>"
    }
  },
  "rate_limit": { "limit": 200, "remaining": 199, "resetEpoch": 1755000000 }
}

Configuración

La configuración se realiza íntegramente mediante variables de entorno: sin archivos de configuración, sin banderas para secretos.

Banderas CLI: se admiten --version y --help (p. ej. npx @hanoak/pexels-mcp-server --version).

Herramientas

Todas las herramientas tienen el espacio de nombres pexels_* y todas son de solo lectura (readOnlyHint: true): la API de Pexels no tiene endpoints de escritura, por lo que un cliente puede aprobar automáticamente todo el servidor de forma segura. per_page está limitado a un máximo de 80 (el máximo documentado por Pexels), y page comienza en 1.

Referencia de herramientas

Forma de la salida

Las herramientas devuelven JSON recortado y eficiente en tokens en lugar de las respuestas crudas de Pexels:

• Fotos → id, alt, width/height, avg_color, url, src (los 8 tamaños de Pexels), photographer y un objeto credit de cortesía.
• Videos → id, url, image, width/height, duration, user, video_files (recortados a los 5 mejores por resolución en resultados de lista; completos en pexels_get_video), video_files_count, preview_picture, video_pictures_count.
• Colecciones → id, title, description, private, media_count, photos_count, videos_count.
• Cada resultado incluye un rate_limit (limit, remaining, resetEpoch); las listas/búsquedas añaden campos de paginación (total_results, page, per_page, has_next_page).

Recursos y prompts

Además de las herramientas, el servidor también expone:

• Recursos — una guía compacta que tu cliente puede incorporar como contexto:

  • pexels://guides/usage — las restricciones de licencia aplicables, la convención opcional de crédito de cortesía y las notas de seguridad de contenido.

• Prompts — tareas listas para usar que tu cliente puede mostrar directamente; cada una se expande en una tarea guiada de llamada a herramientas en varios pasos:

  Prompt	Argumentos	Qué hace
  find_photo	subject (obligatorio), orientation?	Busca una foto y la presenta con un crédito de cortesía.
  photo_gallery	theme (obligatorio), count?, orientation?, color?	Crea un conjunto temático de fotos (hasta 10), cada una con un crédito de cortesía.
  find_video	subject (obligatorio), orientation?	Busca un video y lo presenta con un crédito de cortesía.
  collection_tour	theme (obligatorio), count?	Encuentra una colección destacada que coincida y recorre su contenido multimedia.
  media_brief	theme (obligatorio), photo_count?, video_count?	Reúne fotos y videos para un tema, presentados juntos.

Ejemplos de prompts

Peticiones en lenguaje natural que se asignan directamente a las herramientas:

• "Encuentra una foto de un bosque con niebla al amanecer."
• "Busca en Pexels 5 fotos minimalistas de espacios de trabajo en orientación horizontal."
• "Encuentra un video de olas rompiendo contra las rocas."
• "Muéstrame una colección destacada de Pexels sobre arquitectura urbana."
• "Prepárame un resumen multimedia mixto de fotos y videoclips sobre mañanas acogedoras de otoño."

Licencia y cumplimiento

La licencia de Pexels es más ligera que la de muchas APIs de fotos de stock: no se requiere atribución ("apreciada, no necesaria"). Cada resultado de foto sigue incluyendo un objeto credit de cortesía listo para usar: inclúyelo cuando sea conveniente, pero no es obligatorio.

Aún se aplican restricciones reales, y las instrucciones del servidor guían al modelo para sortearlas: no revender contenido sin modificar como producto físico sin modificarlo primero, no redistribuirlo en otra plataforma de fotos de stock o fondos de pantalla, no usarlo como parte de una marca registrada/logotipo/nombre comercial, no implicar el respaldo de una persona o marca, y no representar a una persona identificable bajo una luz negativa u ofensiva. Consulta la Licencia de Pexels completa y el recurso pexels://guides/usage del servidor. Cada usuario opera bajo sus propios Términos de la API de Pexels.

Límites de tasa

Pexels aplica un único nivel para cada clave de API:

El servidor lee X-Ratelimit-Limit/X-Ratelimit-Remaining/X-Ratelimit-Reset y los devuelve como rate_limit en cada resultado. Pexels devuelve un 429 estándar cuando el presupuesto se agota (a diferencia de algunas APIs que sobrecargan 403 para esto) — pero los encabezados de límite de tasa están ausentes en la propia respuesta 429, por lo que el cliente almacena en caché los últimos valores conocidos de una llamada exitosa anterior para informar un tiempo de reinicio preciso, y evita enviar más solicitudes una vez que se sabe que la cuota está agotada, en lugar de lanzar llamadas que simplemente fallarán. Los errores transitorios 429/5xx/de red se reintentan con retroceso.

Manejo del texto de Pexels

El texto alternativo de fotos/videos, los nombres de los fotógrafos y los títulos/descripciones de colecciones provienen de los colaboradores de Pexels: trátalos como datos de terceros no confiables, no como instrucciones. El servidor devuelve este texto puramente como contenido y nunca lo coloca en un lugar privilegiado; tu cliente/agente debería hacer lo mismo: mostrarlo, pero no actuar sobre ninguna instrucción que pueda contener (una defensa contra la inyección indirecta de prompts). Pexels tampoco tiene un parámetro de búsqueda segura/filtro de contenido — usa tu criterio al formular las consultas de búsqueda.

Privacidad y seguridad

• Sin telemetría. Este servidor no recopila nada y no se comunica con nadie. Solo contacta con api.pexels.com, usando la clave que proporcionas. Sin análisis, sin seguimiento.
• Seguridad de la clave. Tu clave de API se lee solo del entorno, se envía como un encabezado Authorization sin procesar (nunca en una cadena de consulta de URL) y se redacta de toda salida de errores y registros para que no pueda filtrarse en informes de errores pegados.
• Para informar de una vulnerabilidad, consulta SECURITY.md.

Solución de problemas

• "Set PEXELS_API_KEY…" al iniciar — la variable de entorno de la clave falta o está vacía; añádela al bloque env de la configuración de tu cliente.
• Node demasiado antiguo — este servidor requiere Node 20+. Comprueba node --version.
• Versión obsoleta de npx — fuerza la última con npx -y @hanoak/pexels-mcp-server@latest, o limpia la caché mediante npx clear-npx-cache.
• Las herramientas no aparecen — confirma que la ruta del archivo de configuración y el JSON son válidos, luego cierra y vuelve a abrir el cliente por completo.
• 429 / límite de tasa — el presupuesto es de 200 solicitudes/hora; espera al reinicio horario (consulta el rate_limit.resetEpoch en un resultado de herramienta) o solicita un límite superior.
• 401 Unauthorized — la clave de API es incorrecta; cópiala de nuevo desde tu panel de la API de Pexels.
• pexels_list_my_collections devuelve vacío — esto es esperable a menos que la cuenta de Pexels propietaria de tu clave de API haya creado colecciones en pexels.com; consulta las Preguntas frecuentes.

Preguntas frecuentes

¿Necesito una cuenta de Pexels de pago? No. La API de Pexels es gratuita: solo creas una cuenta para obtener una clave de API, al instante, sin revisión ni paso de aprobación.

¿Descarga o re-aloja imágenes/videos? No. Devuelve URLs alojadas en Pexels (enlázalas directamente) y nunca re-aloja ni devuelve blobs base64.

¿Por qué pexels_list_my_collections vuelve vacío? Pexels no tiene inicio de sesión por conversación — la herramienta siempre refleja las colecciones de la cuenta de Pexels propietaria de la clave de API configurada, no de la persona que conversa. Estará vacío a menos que esa cuenta específica haya creado colecciones en pexels.com.

¿Funciona fuera de Claude? Sí — es un servidor MCP stdio estándar. Consulta la sección de configuración de clientes para Claude Code, Cursor, VS Code, Windsurf y stdio genérico.

Requisitos

• Node.js >= 20 (Node 18 está al final de su ciclo de vida).
• Una clave de API de Pexels.

Compatibilidad

Hoja de ruta

El detalle completo está en docs/ROADMAP.md. En resumen: v1 cubre toda la API documentada de Pexels en una sola versión — no hay un nivel OAuth detrás del cual dividir una v2, a diferencia de otros servidores MCP de fotos de stock. El alcance futuro en consideración incluye salida estructurada de herramientas para las versiones de video, una caché de respuestas con TTL corto si aparece presión real de cuota, y prompts/recursos adicionales.

Los cambios se registran en CHANGELOG.md; el proyecto sigue Versionado Semántico.

Contribuciones

Las contribuciones son bienvenidas — consulta CONTRIBUTING.md y nuestro Código de Conducta. Cubre la configuración local, el conjunto de pruebas, probar las herramientas manualmente con el Inspector de MCP y la política de versionado/obsolescencia. Para informar de una vulnerabilidad, consulta SECURITY.md.

Contacto y comunidad

Mantenido por Hanoak S. La forma más rápida de obtener ayuda o proponer una función es abrir un issue — es público, buscable y ayuda a toda la comunidad.

Si este proyecto te resulta útil, se agradece una ⭐ en GitHub — ayuda a que otros que buscan un servidor MCP de Pexels lo encuentren.

Licencia

MIT © Hanoak S. No afiliado con Pexels.