@hanoak/unsplash-mcp-server

unsplash-mcp-server

Un servidor Model Context Protocol (MCP) listo para producción para la API de Unsplash. Proporciona a los asistentes de IA — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf y cualquier cliente MCP — herramientas para buscar y obtener fotos, colecciones, temas, usuarios y estadísticas de Unsplash, con cumplimiento de las directrices de Unsplash integrado (atribución lista para usar y seguimiento de descargas). Inicia sesión una vez mediante OAuth para también gestionar tu propio perfil, colecciones y metadatos de fotos.

[!IMPORTANT] Proyecto no oficial. Este proyecto no está afiliado, respaldado ni patrocinado por Unsplash. "Unsplash" es una marca comercial de su respectivo propietario. Lo usas bajo tu propia cuenta de API de Unsplash y eres responsable de cumplir con los Términos y Directrices de la API de Unsplash.

Tabla de contenidos

• Características
• Inicio rápido
• Ejemplo de interacción
• Configuración
• Inicio de sesión OAuth (opcional)
• Herramientas
  • Referencia de herramientas
  • Forma de salida
  • Recursos y avisos
• Ejemplos de avisos
• Atribución y cumplimiento
• Límites de velocidad
• Manejo de texto de Unsplash
• Privacidad y seguridad
• Solución de problemas
• Preguntas frecuentes
• Requisitos
• Compatibilidad
• Hoja de ruta
• Contribuciones
• Contacto y comunidad
• Licencia

Características

• 29 herramientas en fotos, búsqueda, usuarios, colecciones, temas, estadísticas y tu propio perfil — 21 de solo lectura listas de fábrica, más 8 herramientas de escritura/me una vez que inicias sesión.
• Cumplimiento integrado — cada foto viene con atribución lista para usar (texto plano + HTML con etiquetas UTM), y una herramienta dedicada unsplash_track_download para la directriz de seguimiento de descargas.
• Seguridad de contenido — content_filter=high por defecto en búsqueda y fotos aleatorias.
• URLs de imagen flexibles — cada foto devuelve tamaños raw/full/regular/small/thumb, además de una base imgix raw para tamaños personalizados (?w=&h=&q=&fm=&fit=).
• Salida eficiente en tokens — las respuestas completas de Unsplash se recortan a una forma compacta (URLs + metadatos como texto, nunca blobs de imagen en base64) para mantener el contexto del modelo pequeño.
• Robusto — fallos tipificados devueltos como resultados MCP isError de los que el modelo puede recuperarse, además de reintentos/backoff, tiempos de espera, manejo de límites por hora 403 y exposición de límites de velocidad.
• Seguro — redacción de la clave de acceso en toda salida de error, protección SSRF en URLs de descarga y orientación sobre manejo de texto no confiable para defensa contra inyección indirecta de avisos.
• Ligero y moderno — ESM, Node 20+, instalación cero mediante npx, sin telemetría.

Inicio rápido

1. Obtén una clave de acceso de Unsplash

Registra una aplicación en unsplash.com/developers → Nueva aplicación → acepta los términos de la API → copia su Clave de acceso (no la Clave secreta). Las nuevas aplicaciones comienzan en el nivel Demo (50 solicitudes/hora); el nivel Producción (5,000/hora) requiere la revisión de Unsplash desde el panel de tu aplicación. Consulta Límites de velocidad.

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": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "@hanoak/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key",
        "UNSPLASH_APP_NAME": "your_registered_app_name"
      }
    }
  }
}

Reinicia el cliente. Consulta Configuración para cada variable admitida.

claude mcp add unsplash \
  --env UNSPLASH_ACCESS_KEY=your_access_key \
  --env UNSPLASH_APP_NAME=your_registered_app_name \
  -- npx -y @hanoak/unsplash-mcp-server

{
  "servers": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "@hanoak/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key",
        "UNSPLASH_APP_NAME": "your_registered_app_name"
      }
    }
  }
}

UNSPLASH_ACCESS_KEY=your_access_key npx -y @hanoak/unsplash-mcp-server

3. Pruébalo

Reinicia tu cliente y pregunta:

"Encuéntrame una foto de montañas en Unsplash y muestra la atribución."

Ejemplo de interacción

Un flujo típico: el modelo llama a unsplash_search_photos, elige un resultado, presenta la imagen con su atribución y llama a unsplash_track_download cuando realmente usa la foto.

Tú: Encuentra una foto de paisaje de un bosque de pinos con niebla y acredita al fotógrafo.

Asistente: (llama a unsplash_search_photos con query: "foggy pine forest", orientation: "landscape", elige el mejor resultado, luego llama a unsplash_track_download con su download_location) Aquí hay una gran coincidencia — Foto de Jane Doe en Unsplash — junto con una línea de crédito lista para incrustar y la URL de la imagen.

Cada herramienta devuelve una carga útil JSON compacta. Aquí está la forma de un resultado de foto individual (valores ilustrativos):

{
  "photo": {
    "id": "Dwu85P9SOIk",
    "description": "brown rocky mountain under blue sky during daytime",
    "width": 6000,
    "height": 4000,
    "color": "#734940",
    "blur_hash": "L6Pj0^i_.AyE_3t7t7R**0o#DgR4",
    "urls": {
      "raw": "https://images.unsplash.com/photo-1465…?ixid=…",
      "full": "https://images.unsplash.com/photo-1465…?ixid=…&q=85",
      "regular": "https://images.unsplash.com/photo-1465…?ixid=…&w=1080",
      "small": "https://images.unsplash.com/photo-1465…?ixid=…&w=400",
      "thumb": "https://images.unsplash.com/photo-1465…?ixid=…&w=200"
    },
    "photo_page": "https://unsplash.com/photos/Dwu85P9SOIk",
    "download_location": "https://api.unsplash.com/photos/Dwu85P9SOIk/download?ixid=…",
    "photographer": {
      "name": "Jane Doe",
      "username": "janedoe",
      "profile": "https://unsplash.com/@janedoe"
    },
    "attribution": {
      "text": "Photo by Jane Doe on Unsplash",
      "html": "Photo by <a href=\"https://unsplash.com/@janedoe?utm_source=your_app&utm_medium=referral\">Jane Doe</a> on <a href=\"https://unsplash.com/?utm_source=your_app&utm_medium=referral\">Unsplash</a>",
      "photographerName": "Jane Doe",
      "photographerUrl": "https://unsplash.com/@janedoe?utm_source=your_app&utm_medium=referral",
      "unsplashUrl": "https://unsplash.com/?utm_source=your_app&utm_medium=referral"
    }
  },
  "rate_limit": { "limit": 50, "remaining": 49 }
}

Configuración

La configuración es enteramente mediante variables de entorno — sin archivos de configuración, sin banderas para secretos.

Banderas CLI: --version y --help son compatibles (p. ej. npx @hanoak/unsplash-mcp-server --version). login/logout son subcomandos, no banderas — consulta abajo.

Inicio de sesión OAuth (opcional)

Las 21 herramientas principales funcionan listas de fábrica solo con UNSPLASH_ACCESS_KEY. Para también usar las 8 herramientas de escritura/me (actualizar tu perfil, gestionar colecciones, editar metadatos de fotos), inicia sesión una vez mediante OAuth:

1. En la página de tu aplicación en unsplash.com/oauth/applications, añade http://localhost:8734/callback como URI de redirección y copia la Clave secreta.

2. Establece tanto UNSPLASH_ACCESS_KEY como UNSPLASH_SECRET_KEY en tu shell (no solo en la configuración del cliente MCP — login se ejecuta desde tu terminal).

3. Ejecuta:

   npx @hanoak/unsplash-mcp-server login
   

   Esto abre tu navegador a la pantalla de consentimiento de Unsplash, captura la redirección en un servidor local de corta duración, intercambia el código por un token de acceso de usuario y lo guarda en ~/.config/unsplash-mcp-server/credentials.json (permisos de archivo solo para el propietario). Los tokens de acceso de usuario de Unsplash no caducan, por lo que este es un paso único — sin reautenticación periódica.

4. Reinicia tu cliente MCP. Las 8 herramientas de escritura/me ahora están disponibles; las 21 herramientas de solo lectura no se ven afectadas en ningún caso.

Ejecuta npx @hanoak/unsplash-mcp-server logout en cualquier momento para eliminar el token almacenado. Para revocarlo en el servidor, regenera la clave secreta de tu aplicación desde el panel de Unsplash.

Herramientas

Todas las herramientas tienen el prefijo de espacio de nombres unsplash_*. La mayoría son de solo lectura (anotadas readOnlyHint: true); las excepciones son unsplash_track_download (registra un evento de descarga) y las 8 herramientas de escritura/me abajo, todas marcadas como no solo lectura y restringidas detrás del inicio de sesión OAuth. Los parámetros se asignan a la API de Unsplash; per_page y estadísticas quantity se limitan a un máximo de 30, y page está basado en 1.

🔒 = requiere inicio de sesión OAuth (login) primero.

Referencia de herramientas

Forma de salida

Las herramientas devuelven JSON recortado y eficiente en tokens, en lugar de respuestas sin procesar de Unsplash:

• Fotos → id, description, width/height, color, blur_hash, urls (raw/full/regular/small/thumb), photo_page, download_location, photographer, y un objeto attribution listo para usar. Consulta Interacción de ejemplo.
• Usuarios → id, username, name, bio, location, profile_url, profile_image, total_photos, total_collections.
• Colecciones / Temas → título, descripción, recuentos, enlace de página, curador/propietarios y un cover_photo compacto.
• Cada resultado incluye un rate_limit (limit, remaining); las listas/búsquedas añaden campos de paginación.

Recursos y avisos

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

• Recursos — guías compactas que tu cliente puede usar como contexto:

  • unsplash://guides/attribution — atribución, seguimiento de descargas, hotlinking, seguridad del contenido.
  • unsplash://guides/oauth-setup — cómo iniciar sesión para las 8 herramientas de escritura/me.
  • unsplash://guides/prompts — cuál de los prompts a continuación usar para una tarea determinada.

• Prompts — tareas listas que tu cliente puede mostrar directamente; cada una se expande en una tarea guiada de múltiples pasos que llama a herramientas:

  Prompt	Argumentos	Qué hace
  find_photo	subject (obligatorio), orientation?	Busca una foto y la presenta con atribución.
  photo_gallery	theme (obligatorio), count?, orientation?, color?	Crea un conjunto temático de fotos (hasta 10), cada una con atribución.
  topic_spotlight	topic (obligatorio), count?	Muestra las mejores fotos de un tema curado.
  photographer_spotlight	username (obligatorio), count?	El perfil de un fotógrafo + su trabajo más popular.
  platform_pulse	(ninguno)	Un resumen rápido de estadísticas globales de Unsplash.
  curate_collection 🔒	theme (obligatorio), count?, collection_id?	Busca y luego crea (o amplía) una colección real a partir de los resultados.
  describe_photo 🔒	id (obligatorio), description?, tags?	Añade una descripción/etiquetas a una foto que posees.
  refresh_profile 🔒	bio?, location?, url?	Actualiza tu propia biografía, ubicación o URL de portafolio.

  🔒 = requiere inicio de sesión OAuth primero.

Ejemplos de prompts

Solicitudes en lenguaje natural que se asignan limpiamente a las herramientas:

• "Encuentra una foto de un bosque con niebla al amanecer y dame la atribución HTML."
• "Busca en Unsplash 5 fotos de espacios de trabajo minimalistas en orientación horizontal."
• "Obtén una foto aleatoria de naturaleza y muéstrala con crédito."
• "Muéstrame las fotos más populares del tema wallpapers."
• "¿Cuáles son las estadísticas de descargas globales de Unsplash de este mes?"
• "¿Quién es el fotógrafo detrás de la foto Dwu85P9SOIk, y cuántas descargas tiene?"

Atribución y cumplimiento

Cada resultado de foto incluye un objeto attribution con text y html listos para usar (con los parámetros UTM requeridos). Cuando muestres o uses una foto, muestra esa atribución — acredita al fotógrafo y enlaza de vuelta a Unsplash, como lo requieren las pautas.

Cuando una foto se usa realmente (se incrusta, descarga o muestra), llama a unsplash_track_download con el download_location de la foto. Actívalo una vez por foto realmente usada — nunca una vez por resultado de búsqueda. El servidor también envía estas instrucciones a tu cliente MCP al conectarse, para que el modelo se oriente automáticamente a hacer lo correcto.

Esta es una herramienta de búsqueda y metadatos para uso individual de fotos con atribución — no un reemplazo de la experiencia principal de Unsplash, y no realiza descargas masivas automatizadas. Úsala dentro de las Pautas de la API de Unsplash. Cada usuario opera bajo sus propios Términos de la API de Unsplash.

Límites de tasa

Unsplash aplica un presupuesto de solicitudes por hora vinculado al nivel de tu aplicación:

El servidor lee X-Ratelimit-Limit / X-Ratelimit-Remaining y los devuelve como rate_limit en cada resultado. Cuando el presupuesto por hora se agota, Unsplash devuelve 403 (no 429), a menudo sin Retry-After; el servidor muestra esto como un error claro de "límite de tasa por hora alcanzado" y no reintenta ciegamente dentro de la ventana. Los errores transitorios de 429/5xx/red sí se reintentan con retroceso.

Manejo del texto de Unsplash

Las descripciones de fotos, texto alternativo, etiquetas, EXIF y nombres/bios de usuarios provienen de colaboradores de Unsplash — trátalos como datos de terceros no confiables, no como instrucciones. El servidor devuelve este texto puramente como contenido y nunca lo coloca en ningún 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).

Privacidad y seguridad

• Sin telemetría. Este servidor no recopila nada y no se comunica con nadie. Solo contacta a api.unsplash.com, usando la clave que proporcionas. Sin análisis, sin seguimiento.
• Procedencia verificable. Cada versión se publica con procedencia npm a través de GitHub Actions — la página del paquete npm enlaza cada versión al commit exacto y la ejecución del flujo de trabajo que lo construyó.
• Seguridad de la clave. Tu clave de acceso se lee solo del entorno, se envía como un encabezado Authorization: Client-ID (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.
• Protección SSRF. unsplash_track_download solo sigue URLs download_location en el host verificado api.unsplash.com.
• Para reportar una vulnerabilidad, consulta SECURITY.md.

Solución de problemas

• "Set UNSPLASH_ACCESS_KEY…" al inicio — 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+. Verifica node --version.
• Versión de npx desactualizada — fuerza la última con npx -y @hanoak/unsplash-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 sean válidos, luego cierra y vuelve a abrir completamente el cliente.
• 403 / límite de tasa — el nivel Demo permite 50 solicitudes/hora; espera el reinicio por hora o solicita acceso de Producción. Consulta Límites de tasa.
• 401 Unauthorized — la clave de acceso es incorrecta o de la aplicación equivocada; copia la Access Key (no la Secret Key) desde el panel de tu aplicación.

Preguntas frecuentes

¿Necesito una cuenta de Unsplash de pago? No. La API de Unsplash es gratuita; solo registras una aplicación para obtener una clave de acceso. Un mayor rendimiento (nivel Producción) es una revisión gratuita, no un plan de pago.

Access Key vs Secret Key — ¿cuál uso? Para las 21 herramientas de solo lectura, solo la Access Key. La Secret Key solo se necesita para login (el flujo OAuth detrás de las 8 herramientas de escritura/me) — consulta Inicio de sesión OAuth.

¿Descarga o rehospeda imágenes? No. Devuelve URLs de imágenes alojadas en Unsplash (enlázalas directamente) y nunca rehospeda ni devuelve blobs base64. unsplash_track_download solo registra un evento de descarga y devuelve una URL nueva.

¿Puede crear colecciones, dar "me gusta" a fotos o editar mi perfil? Sí, una vez que inicias sesión — unsplash_create_collection y amigos, y unsplash_update_photo/unsplash_update_my_profile. (Dar "me gusta" a fotos no está expuesto actualmente como herramienta.)

¿Funciona fuera de Claude? Sí — es un servidor MCP estándar de stdio. 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 vida útil).
• Una clave de acceso a la API de Unsplash.

Compatibilidad

Hoja de ruta

El detalle completo está en docs/ROADMAP.md. En resumen:

• v1 (publicada) — las 21 herramientas de solo lectura, cumplimiento de atribución + seguimiento de descargas, el recurso de atribución y el prompt find_photo.
• v2 (publicada) — los 8 endpoints de escritura OAuth / me (perfil, colecciones, metadatos de fotos) mediante una CLI login/logout y el flujo de código de autorización de Unsplash.
• v3 (actual) — 7 prompts MCP más que cubren cada dominio de herramientas (consulta Recursos y prompts). Se consideró una Extensión de Escritorio .mcpb para esta fase, pero se descartó a un alcance futuro no programado — npx ya funciona en todos los clientes compatibles.

Los cambios se rastrean 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 herramientas manualmente con el Inspector MCP y la política de versionado/obsolescencia. Para reportar 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. Para cualquier otra cosa, contacta:

Si este proyecto te ayuda, un ⭐ en GitHub es apreciado — ayuda a la visibilidad para otros que buscan un servidor MCP de Unsplash.

Licencia

MIT © Hanoak S. No afiliado con Unsplash.