@hanoak/unsplash-mcp-server

unsplash-mcp-server

Um servidor Model Context Protocol (MCP) pronto para produção para a API do Unsplash. Ele fornece a assistentes de IA — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf e qualquer cliente MCP — ferramentas para pesquisar e buscar fotos, coleções, tópicos, usuários e estatísticas do Unsplash, com conformidade com as diretrizes do Unsplash incorporada (atribuição pronta para uso e rastreamento de downloads). Faça login uma vez via OAuth para também gerenciar seu próprio perfil, coleções e metadados de fotos.

[!IMPORTANT] Projeto não oficial. Este projeto não é afiliado, endossado ou patrocinado pelo Unsplash. "Unsplash" é uma marca registrada de seu respectivo proprietário. Você o utiliza sob sua própria conta de API do Unsplash e é responsável por cumprir os Termos e Diretrizes da API do Unsplash.

Sumário

• Recursos
• Início rápido
• Exemplo de interação
• Configuração
• Login OAuth (opcional)
• Ferramentas
  • Referência de ferramentas
  • Formato de saída
  • Recursos e prompts
• Exemplos de prompts
• Atribuição e conformidade
• Limites de taxa
• Tratamento de texto do Unsplash
• Privacidade e segurança
• Solução de problemas
• Perguntas frequentes
• Requisitos
• Compatibilidade
• Roteiro
• Contribuição
• Contato e comunidade
• Licença

Recursos

• 29 ferramentas em fotos, pesquisa, usuários, coleções, tópicos, estatísticas e seu próprio perfil — 21 somente leitura prontas para uso, além de 8 ferramentas de escrita/me após você fazer login.
• Conformidade incorporada — cada foto vem com atribuição pronta para uso (texto simples + HTML com tags UTM) e uma ferramenta dedicada unsplash_track_download para a diretriz de rastreamento de downloads.
• Segurança de conteúdo — content_filter=high por padrão em pesquisa e fotos aleatórias.
• URLs de imagem flexíveis — cada foto retorna tamanhos raw/full/regular/small/thumb, além de uma base imgix raw para tamanhos personalizados (?w=&h=&q=&fm=&fit=).
• Saída eficiente em tokens — respostas completas do Unsplash são reduzidas a um formato compacto (URLs + metadados como texto, nunca blobs de imagem em base64) para manter o contexto do modelo pequeno.
• Robusto — falhas tipadas retornadas como resultados MCP isError dos quais o modelo pode se recuperar, além de tentativas/backoff, timeouts, tratamento de limite horário 403 e exposição de limites de taxa.
• Seguro — redação da chave de acesso em toda saída de erro, proteção SSRF em URLs de download e orientação de tratamento de texto não confiável para defesa contra injeção indireta de prompts.
• Enxuto e moderno — ESM, Node 20+, instalação zero via npx, sem telemetria.

Início rápido

1. Obtenha uma chave de acesso do Unsplash

Registre um aplicativo em unsplash.com/developers → Novo aplicativo → aceite os termos da API → copie sua Chave de acesso (não a Chave secreta). Novos aplicativos começam no nível Demo (50 solicitações/hora); o nível Produção (5.000/hora) requer a revisão do Unsplash a partir do painel do seu aplicativo. Consulte Limites de taxa.

2. Adicione o servidor ao seu cliente MCP

Claude Desktop — edite 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"
      }
    }
  }
}

Reinicie o cliente. Consulte Configuração para cada variável suportada.

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. Experimente

Reinicie seu cliente e pergunte:

"Encontre uma foto de montanhas no Unsplash e mostre a atribuição."

Exemplo de interação

Um fluxo típico: o modelo chama unsplash_search_photos, escolhe um resultado, apresenta a imagem com sua atribuição e chama unsplash_track_download quando realmente usa a foto.

Você: Encontre uma foto de paisagem de uma floresta de pinheiros com neblina e credite o fotógrafo.

Assistente: (chama unsplash_search_photos com query: "foggy pine forest", orientation: "landscape", escolhe o melhor resultado e depois chama unsplash_track_download com seu download_location) Aqui está uma ótima correspondência — Foto de Jane Doe no Unsplash — junto com uma linha de crédito pronta para incorporar e a URL da imagem.

Cada ferramenta retorna um payload JSON compacto. Aqui está o formato de um único resultado de foto (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 }
}

Configuração

A configuração é inteiramente por meio de variáveis de ambiente — sem arquivos de configuração, sem flags para segredos.

Flags de CLI: --version e --help são suportadas (por exemplo, npx @hanoak/unsplash-mcp-server --version). login/logout são subcomandos, não flags — veja abaixo.

Login OAuth (opcional)

As 21 ferramentas principais funcionam prontas para uso apenas com UNSPLASH_ACCESS_KEY. Para também usar as 8 ferramentas de escrita/me (atualizar seu perfil, gerenciar coleções, editar metadados de fotos), faça login uma vez via OAuth:

1. Na página do seu aplicativo em unsplash.com/oauth/applications, adicione http://localhost:8734/callback como URI de redirecionamento e copie a Chave secreta.

2. Defina tanto UNSPLASH_ACCESS_KEY quanto UNSPLASH_SECRET_KEY no seu shell (não apenas na configuração do cliente MCP — login é executado a partir do seu terminal).

3. Execute:

   npx @hanoak/unsplash-mcp-server login
   

   Isso abre seu navegador para a tela de consentimento do Unsplash, captura o redirecionamento em um servidor local de curta duração, troca o código por um token de acesso do usuário e o salva em ~/.config/unsplash-mcp-server/credentials.json (permissões de arquivo somente do proprietário). Os tokens de acesso do usuário do Unsplash não expiram, então este é um passo único — sem reautenticação periódica.

4. Reinicie seu cliente MCP. As 8 ferramentas de escrita/me agora estão disponíveis; as 21 ferramentas somente leitura não são afetadas de qualquer forma.

Execute npx @hanoak/unsplash-mcp-server logout a qualquer momento para remover o token armazenado. Para revogá-lo no lado do servidor, regenere a chave secreta do seu aplicativo no painel do Unsplash.

Ferramentas

Todas as ferramentas têm namespace unsplash_*. A maioria é somente leitura (anotada readOnlyHint: true); as exceções são unsplash_track_download (registra um evento de download) e as 8 ferramentas de escrita/me abaixo, todas marcadas como não somente leitura e protegidas por Login OAuth. Os parâmetros mapeiam para a API do Unsplash; per_page e estatísticas quantity são limitados a um máximo de 30, e page é baseado em 1.

🔒 = requer Login OAuth (login) primeiro.

Referência de ferramentas

Formato de saída

As ferramentas retornam JSON enxuto e eficiente em tokens, em vez das respostas brutas do Unsplash:

• Fotos → id, description, width/height, color, blur_hash, urls (raw/full/regular/small/thumb), photo_page, download_location, photographer e um objeto attribution pronto para uso. Veja Exemplo de interação.
• Usuários → id, username, name, bio, location, profile_url, profile_image, total_photos, total_collections.
• Coleções / Tópicos → título, descrição, contagens, link da página, curadores/proprietários e um cover_photo compacto.
• Cada resultado inclui um rate_limit (limit, remaining); listas/buscas adicionam campos de paginação.

Recursos e prompts

Além das ferramentas, o servidor também expõe:

• Recursos — guias compactos que seu cliente pode usar como contexto:

  • unsplash://guides/attribution — atribuição, rastreamento de downloads, hotlinking, segurança de conteúdo.
  • unsplash://guides/oauth-setup — como entrar para as 8 ferramentas de escrita/me.
  • unsplash://guides/prompts — quais dos prompts abaixo usar para uma determinada tarefa.

• Prompts — tarefas prontas que seu cliente pode exibir diretamente; cada uma se expande em uma tarefa guiada de chamada de ferramenta em várias etapas:

  Prompt	Argumentos	O que faz
  find_photo	subject (obrigatório), orientation?	Busca uma foto e a apresenta com atribuição.
  photo_gallery	theme (obrigatório), count?, orientation?, color?	Cria um conjunto temático de fotos (até 10), cada uma com atribuição.
  topic_spotlight	topic (obrigatório), count?	Mostra as melhores fotos de um tópico selecionado.
  photographer_spotlight	username (obrigatório), count?	Perfil de um fotógrafo + seus trabalhos mais populares.
  platform_pulse	(nenhum)	Um resumo rápido de estatísticas gerais do Unsplash.
  curate_collection 🔒	theme (obrigatório), count?, collection_id?	Busca e depois cria (ou amplia) uma coleção real a partir dos resultados.
  describe_photo 🔒	id (obrigatório), description?, tags?	Adiciona uma descrição/tags a uma foto sua.
  refresh_profile 🔒	bio?, location?, url?	Atualiza sua bio, localização ou URL do portfólio.

  🔒 = exige entrada via OAuth primeiro.

Exemplos de prompts

Perguntas em linguagem natural que mapeiam diretamente para as ferramentas:

• "Encontre uma foto de uma floresta com neblina ao amanhecer e me dê a atribuição em HTML."
• "Busque no Unsplash 5 fotos de espaço de trabalho minimalista na orientação paisagem."
• "Obtenha uma foto aleatória da natureza e mostre-a com crédito."
• "Mostre-me as fotos mais populares no tópico wallpapers."
• "Quais são as estatísticas de downloads do Unsplash deste mês?"
• "Quem é o fotógrafo por trás da foto Dwu85P9SOIk, e quantos downloads ela tem?"

Atribuição e conformidade

Cada resultado de foto inclui um objeto attribution com text e html prontos para uso (com os parâmetros UTM obrigatórios). Ao exibir ou usar uma foto, mostre essa atribuição — ela credita o fotógrafo e vincula de volta ao Unsplash, conforme exigem as diretrizes.

Quando uma foto for realmente usada (incorporada, baixada, exibida), chame unsplash_track_download com o download_location da foto. Dispare uma vez por foto realmente usada — nunca uma vez por resultado de busca. O servidor também envia essas instruções ao seu cliente MCP na conexão, para que o modelo seja incentivado a fazer a coisa certa automaticamente.

Esta é uma ferramenta de busca e metadados para uso individual e atribuído de fotos — não um substituto para a experiência principal do Unsplash, e não realiza download automatizado em massa. Use-a dentro das Diretrizes da API do Unsplash. Cada usuário opera sob seus próprios Termos da API do Unsplash.

Limites de taxa

O Unsplash aplica um orçamento de solicitações por hora vinculado ao nível do seu aplicativo:

O servidor lê X-Ratelimit-Limit / X-Ratelimit-Remaining e os retorna como rate_limit em cada resultado. Quando o orçamento horário é esgotado, o Unsplash retorna 403 (não 429), muitas vezes sem Retry-After; o servidor apresenta isso como um erro claro de "limite de taxa horária atingido" e não tenta novamente cegamente dentro da janela. Erros transitórios de 429/5xx/rede são repetidos com backoff.

Tratamento de texto do Unsplash

Descrições de fotos, texto alternativo, tags, EXIF e nomes/bios de usuários vêm de colaboradores do Unsplash — trate-os como dados de terceiros não confiáveis, não como instruções. O servidor retorna esse texto puramente como conteúdo e nunca o coloca em qualquer lugar privilegiado; seu cliente/agente deve fazer o mesmo: exibi-lo, mas não agir sobre quaisquer instruções que possa conter (uma defesa contra injeção indireta de prompt).

Privacidade e segurança

• Sem telemetria. Este servidor não coleta nada e não envia dados para ninguém. Ele contata apenas api.unsplash.com, usando a chave que você fornece. Sem analytics, sem rastreamento.
• Proveniência verificável. Cada versão é publicada com proveniência npm via GitHub Actions — a página do pacote npm vincula cada versão ao commit exato e à execução do workflow que a construiu.
• Segurança da chave. Sua chave de acesso é lida apenas do ambiente, enviada como um cabeçalho Authorization: Client-ID (nunca em uma string de consulta de URL) e redigida de toda saída de erro e logs para que não vaze em relatórios de bug colados.
• Proteção SSRF. unsplash_track_download segue apenas URLs download_location no host verificado api.unsplash.com.
• Para relatar uma vulnerabilidade, consulte SECURITY.md.

Solução de problemas

• "Set UNSPLASH_ACCESS_KEY…" na inicialização — a variável de ambiente da chave está ausente ou em branco; adicione-a ao bloco env da configuração do seu cliente.
• Node muito antigo — este servidor requer Node 20+. Verifique node --version.
• Versão desatualizada do npx — force a versão mais recente com npx -y @hanoak/unsplash-mcp-server@latest, ou limpe o cache via npx clear-npx-cache.
• Ferramentas não aparecendo — confirme se o caminho do arquivo de configuração e o JSON são válidos e, em seguida, feche e reabra completamente o cliente.
• 403 / limite de taxa — o nível Demo permite 50 solicitações/hora; aguarde a reinicialização horária ou solicite acesso de Produção. Consulte Limites de taxa.
• 401 Unauthorized — a chave de acesso está errada ou é de outro aplicativo; copie a Access Key (não a Secret Key) do painel do seu aplicativo.

FAQ

Preciso de uma conta paga no Unsplash? Não. A API do Unsplash é gratuita; você só precisa registrar um aplicativo para obter uma chave de acesso. Maior throughput (nível Produção) é uma revisão gratuita, não um plano pago.

Access Key vs Secret Key — qual usar? Para as 21 ferramentas somente leitura, apenas a Access Key. A Secret Key só é necessária para login (o fluxo OAuth por trás das 8 ferramentas de escrita/me) — consulte Entrada via OAuth.

Ele baixa ou rehospeda imagens? Não. Ele retorna URLs de imagens hospedadas no Unsplash (faça hotlink diretamente) e nunca rehospeda ou retorna blobs base64. unsplash_track_download apenas registra um evento de download e retorna uma URL nova.

Ele pode criar coleções, curtir fotos ou editar meu perfil? Sim, depois que você entrar — unsplash_create_collection e amigos, e unsplash_update_photo/unsplash_update_my_profile. (Curtir fotos não está atualmente exposto como ferramenta.)

Funciona fora do Claude? Sim — é um servidor MCP stdio padrão. Consulte a seção de configuração do cliente para Claude Code, Cursor, VS Code, Windsurf e stdio genérico.

Requisitos

• Node.js >= 20 (Node 18 está em fim de vida).
• Uma chave de acesso da API do Unsplash.

Compatibilidade

Roadmap

Detalhes completos estão em docs/ROADMAP.md. Em resumo:

• v1 (lançada) — as 21 ferramentas somente leitura, conformidade de atribuição + rastreamento de downloads, o recurso de atribuição e o prompt find_photo.
• v2 (lançada) — os 8 endpoints OAuth de escrita / me (perfil, coleções, metadados de fotos) via CLI login/logout e o fluxo de código de autorização do Unsplash.
• v3 (atual) — 7 prompts MCP adicionais cobrindo todos os domínios de ferramentas (consulte Recursos e prompts). Uma Extensão de Desktop .mcpb foi considerada para esta fase, mas foi movida para escopo futuro não agendado — npx já funciona em todos os clientes suportados.

As mudanças são rastreadas em CHANGELOG.md; o projeto segue Versionamento Semântico.

Contribuindo

Contribuições são bem-vindas — consulte CONTRIBUTING.md e nosso Código de Conduta. Ele cobre configuração local, a suíte de testes, testar ferramentas manualmente com o MCP Inspector e a política de versionamento/depreciação. Para relatar uma vulnerabilidade, consulte SECURITY.md.

Contato e comunidade

Mantido por Hanoak S. A maneira mais rápida de obter ajuda ou propor um recurso é abrir uma issue — é pública, pesquisável e ajuda toda a comunidade. Para qualquer outra coisa, entre em contato:

Se este projeto ajudar você, uma ⭐ no GitHub é apreciada — ajuda na descoberta para outros que procuram um servidor MCP do Unsplash.

Licença

MIT © Hanoak S. Não afiliado ao Unsplash.