pexels-mcp-server

pexels-mcp-server

Um servidor Model Context Protocol (MCP) pronto para produção para a API do Pexels. Ele oferece a assistentes de IA — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf e qualquer cliente MCP — ferramentas para pesquisar e buscar fotos, vídeos e coleções do Pexels, cobrindo todos os endpoints documentados pela API do Pexels.

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

Sumário

• Recursos
• Início rápido
• Exemplo de interação
• Configuração
• Ferramentas
  • Referência de ferramentas
  • Formato de saída
  • Recursos e prompts
• Exemplos de prompts
• Licença e conformidade
• Limites de taxa
• Tratamento de texto do Pexels
• Privacidade e segurança
• Solução de problemas
• FAQ
• Requisitos
• Compatibilidade
• Roadmap
• Contribuindo
• Contato e comunidade
• Licença

Recursos

• 9 ferramentas cobrindo todos os endpoints documentados do Pexels — fotos (pesquisa, curadoria, obtenção), vídeos (pesquisa, populares, obtenção) e coleções (destaques, mídia, minhas). O Pexels tem um único nível de autenticação por chave de API e nenhum endpoint de escrita, então não existe um "v1 somente leitura" parcial — esta é a superfície completa.
• Ciente de licença por design — o Pexels não exige atribuição, mas cada foto ainda retorna um credit de cortesia pronto para uso (texto + HTML), e as instruções do servidor orientam o modelo sobre as restrições de licença que se aplicam (sem revenda de conteúdo não alterado, sem redistribuição para outras plataformas de banco de imagens, sem uso de marca/logo, sem endosso implícito).
• URLs reais de imagens e vídeos — cada foto retorna as URLs src pré-dimensionadas do próprio Pexels (original/large2x/large/medium/small/portrait/landscape/tiny); cada vídeo retorna suas versões video_files (reduzidas às poucas de maior resolução em resultados de lista, completas em uma consulta de item único).
• Saída eficiente em tokens — as respostas completas do Pexels são reduzidas a um formato compacto (URLs + metadados como texto, nunca blobs 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 novas tentativas/backoff, timeouts e curto-circuito de cota ciente de limites de taxa (o Pexels omite seus cabeçalhos de limite de taxa em um 429, então o cliente armazena em cache o último horário de redefinição conhecido em vez de adivinhar).
• Seguro — redação da chave de API em toda saída de erro e orientação de tratamento de texto não confiável para defesa contra injeção indireta de prompt.
• Enxuto e moderno — ESM, Node 20+, instalação zero via npx, sem telemetria.

Início rápido

1. Obtenha uma chave de API do Pexels

Crie uma conta gratuita em pexels.com/api e você receberá uma chave de API instantaneamente — sem revisão de aplicativo, sem espera de aprovação.

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": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "@hanoak/pexels-mcp-server"],
      "env": {
        "PEXELS_API_KEY": "your_api_key"
      }
    }
  }
}

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

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

Reinicie seu cliente e pergunte:

"Encontre uma foto de montanhas no Pexels."

Exemplo de interação

Um fluxo típico: o modelo chama pexels_search_photos, escolhe um resultado e apresenta a imagem com seu crédito de cortesia.

Você: Encontre uma foto de paisagem de uma floresta de pinheiros com neblina.

Assistente: (chama pexels_search_photos com query: "foggy pine forest", orientation: "landscape", escolhe o melhor resultado) Aqui está uma ótima correspondência — foto de Jane Doe no Pexels — junto com a URL da imagem e uma linha de crédito pronta para uso.

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

Configuração

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

Flags de CLI: --version e --help são suportadas (ex.: npx @hanoak/pexels-mcp-server --version).

Ferramentas

Todas as ferramentas têm namespace pexels_* e cada uma é somente leitura (readOnlyHint: true) — a API do Pexels não tem endpoints de escrita, então um cliente pode aprovar automaticamente o servidor inteiro com segurança. per_page é limitado a um máximo de 80 (o máximo documentado pelo próprio Pexels), e page é baseado em 1.

Referência de ferramentas

Formato de saída

As ferramentas retornam JSON reduzido e eficiente em tokens, em vez de respostas brutas do Pexels:

• Fotos → id, alt, width/height, avg_color, url, src (todos os 8 tamanhos do Pexels), photographer e um objeto de cortesia credit.
• Vídeos → id, url, image, width/height, duration, user, video_files (limitados aos 5 primeiros por resolução em resultados de lista; completos em pexels_get_video), video_files_count, preview_picture, video_pictures_count.
• Coleções → id, title, description, private, media_count, photos_count, videos_count.
• Cada resultado inclui um rate_limit (limit, remaining, resetEpoch); listas/buscas adicionam campos de paginação (total_results, page, per_page, has_next_page).

Recursos e prompts

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

• Recursos — um guia compacto que seu cliente pode usar como contexto:

  • pexels://guides/usage — as restrições de licença aplicáveis, a convenção opcional de crédito de cortesia e notas de segurança de conteúdo.

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

  Prompt	Argumentos	O que faz
  find_photo	subject (obrigatório), orientation?	Busca uma foto e a apresenta com um crédito de cortesia.
  photo_gallery	theme (obrigatório), count?, orientation?, color?	Cria um conjunto temático de fotos (até 10), cada uma com crédito de cortesia.
  find_video	subject (obrigatório), orientation?	Busca um vídeo e o apresenta com um crédito de cortesia.
  collection_tour	theme (obrigatório), count?	Encontra uma coleção em destaque correspondente e percorre sua mídia.
  media_brief	theme (obrigatório), photo_count?, video_count?	Reúne fotos e vídeos para um tema, apresentados juntos.

Exemplos de prompts

Perguntas em linguagem natural que mapeiam diretamente para as ferramentas:

• "Encontre uma foto de uma floresta enevoada ao amanhecer."
• "Pesquise no Pexels 5 fotos de espaços de trabalho minimalistas em orientação paisagem."
• "Encontre um vídeo de ondas quebrando nas rochas."
• "Mostre-me uma coleção em destaque do Pexels sobre arquitetura urbana."
• "Crie um briefing de mídia mista com fotos e clipes de vídeo sobre manhãs aconchegantes de outono."

Licença e conformidade

A licença do Pexels é mais leve do que muitas APIs de banco de imagens: a atribuição não é obrigatória ("apreciada, não necessária"). Cada resultado de foto ainda inclui um objeto de cortesia credit pronto para uso — inclua-o quando for conveniente, mas não é obrigatório.

Restrições reais ainda se aplicam, e as instruções do servidor orientam o modelo em torno delas: não revender conteúdo inalterado como produto físico sem modificá-lo antes, não redistribuí-lo em outra plataforma de banco de imagens ou papel de parede, não usá-lo como parte de marca registrada/logotipo/nome comercial, não sugerir endosso de uma pessoa ou marca e não retratar uma pessoa identificável de forma negativa ou ofensiva. Consulte a Licença Pexels completa e o recurso pexels://guides/usage do servidor. Cada usuário opera sob seus próprios Termos da API Pexels.

Limites de taxa

O Pexels aplica um único nível para cada chave de API:

O servidor lê X-Ratelimit-Limit/X-Ratelimit-Remaining/X-Ratelimit-Reset e os retorna como rate_limit em cada resultado. O Pexels retorna um 429 padrão quando o orçamento é esgotado (diferente de algumas APIs que sobrecarregam 403 para isso) — mas os cabeçalhos de limite de taxa estão ausentes na própria resposta 429, então o cliente armazena em cache os últimos valores conhecidos de uma chamada bem-sucedida anterior para relatar um tempo de redefinição preciso e interrompe solicitações adicionais quando a cota é conhecida como esgotada, em vez de disparar chamadas que apenas falharão. Erros transitórios de 429/5xx/rede são repetidos com backoff.

Tratamento de texto do Pexels

Texto alternativo de fotos/vídeos, nomes de fotógrafos e títulos/descrições de coleções vêm de colaboradores do Pexels — trate-os como dados não confiáveis de terceiros, não como instruções. O servidor retorna esse texto puramente como conteúdo e nunca o coloca em local privilegiado; seu cliente/agente deve fazer o mesmo: exibi-lo, mas não agir sobre qualquer instrução que possa conter (uma defesa contra injeção indireta de prompt). O Pexels também não possui parâmetro de busca segura/filtro de conteúdo — use bom senso ao formular consultas de busca.

Privacidade e segurança

• Sem telemetria. Este servidor não coleta nada e não envia dados a ninguém. Ele contata apenas api.pexels.com, usando a chave que você fornece. Sem análises, sem rastreamento.
• Segurança da chave. Sua chave de API é lida apenas do ambiente, enviada como um cabeçalho Authorization bruto (nunca em uma string de consulta de URL) e removida de toda saída de erro e logs para que não vaze em relatórios de bug colados.
• Para relatar uma vulnerabilidade, consulte SECURITY.md.

Solução de problemas

• "Defina PEXELS_API_KEY…" na inicialização — a variável de ambiente da chave está ausente ou vazia; 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/pexels-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.
• 429 / limite de taxa — o orçamento é de 200 solicitações/hora; aguarde a redefinição horária (veja o rate_limit.resetEpoch em um resultado de ferramenta) ou solicite um limite maior.
• 401 Unauthorized — a chave de API está incorreta; copie-a novamente do seu painel da API Pexels.
• pexels_list_my_collections retorna vazio — isso é esperado, a menos que a conta Pexels proprietária da sua chave de API tenha criado coleções no pexels.com; consulte o FAQ.

FAQ

Preciso de uma conta Pexels paga? Não. A API Pexels é gratuita — você apenas cria uma conta para obter uma chave de API, instantaneamente, sem revisão ou etapa de aprovação.

Ele baixa ou rehospeda imagens/vídeos? Não. Ele retorna URLs hospedadas no Pexels (faça hotlink diretamente) e nunca rehospeda ou retorna blobs base64.

Por que pexels_list_my_collections retorna vazio? O Pexels não tem login por conversa — a ferramenta sempre reflete as coleções da conta Pexels proprietária da chave de API configurada, não da pessoa conversando. Ficará vazio, a menos que essa conta específica tenha criado coleções no pexels.com.

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 API Pexels.

Compatibilidade

Roadmap

Detalhes completos estão em docs/ROADMAP.md. Em resumo: v1 cobre toda a API Pexels documentada em um único lançamento — não há nível OAuth para dividir uma v2, ao contrário de alguns outros servidores MCP de banco de imagens. Escopo futuro em consideração inclui saída estruturada de ferramentas para versões de vídeo, um cache de resposta de TTL curto se houver pressão real de cota e prompts/recursos adicionais.

As alterações 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, suíte de testes, teste manual de ferramentas 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.

Se este projeto ajudar você, um ⭐ no GitHub é apreciado — ajuda na descoberta por outros que procuram um servidor MCP Pexels.

Licença

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