Pexels MCP Server

Um servidor MCP (Model Context Protocol) para buscar imagens e vídeos gratuitos do Pexels.

🎯 Funcionalidades

• search_photos: Busca fotos por palavras-chave com filtros de orientação, tamanho e cor
• get_photo: Obtém detalhes de uma foto específica pelo ID
• get_curated_photos: Lista fotos curadas pela equipe do Pexels
• search_videos: Busca vídeos por palavras-chave
• get_video: Obtém detalhes de um vídeo específico pelo ID
• get_popular_videos: Lista vídeos populares com filtros de duração e dimensões
• get_featured_collections: Lista coleções em destaque

📋 Pré-requisitos

• Node.js 18+
• Uma API Key do Pexels (gratuita)

🔑 Obtendo sua API Key

1. Acesse https://www.pexels.com/api/
2. Clique em "Get Started" ou "Your API Key"
3. Crie uma conta ou faça login
4. Copie sua API Key

🚀 Instalação

# Clone ou copie o projeto
cd pexels-mcp-server

# Instale as dependências
npm install

# Compile o TypeScript
npm run build

⚙️ Configuração no Claude Code

Opção 1: Via linha de comando

# Defina sua API key como variável de ambiente
export PEXELS_API_KEY="sua_api_key_aqui"

# Adicione o servidor ao Claude Code
claude mcp add pexels node /caminho/completo/para/pexels-mcp-server/build/index.js

Opção 2: Via arquivo de configuração

Adicione ao seu ~/.claude.json (configuração local) ou .mcp.json (configuração do projeto):

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/caminho/completo/para/pexels-mcp-server/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "sua_api_key_aqui"
      }
    }
  }
}

🧪 Testando com o MCP Inspector

O MCP Inspector é uma ferramenta útil para testar seu servidor localmente:

# Configure a variável de ambiente
export PEXELS_API_KEY="sua_api_key_aqui"

# Execute o inspector
npm run inspector

📖 Exemplos de Uso

Após configurar o servidor no Claude Code, você pode usar comandos naturais como:

• "Busque fotos de paisagens de montanha"
• "Encontre vídeos de drone sobre cidades à noite"
• "Mostre as fotos curadas do Pexels"
• "Busque fotos azuis em orientação paisagem"
• "Encontre vídeos populares com duração entre 10 e 30 segundos"

⚠️ Atribuição Obrigatória

O Pexels exige que você sempre dê crédito aos fotógrafos. Ao usar as imagens/vídeos:

• Para fotos: "Foto por [Nome do Fotógrafo] no Pexels"
• Para vídeos: "Vídeo por [Nome do Autor] no Pexels"
• Sempre inclua um link para a página original no Pexels quando possível

📊 Rate Limits

Por padrão, a API do Pexels permite:

• 200 requisições por hora
• 20.000 requisições por mês

O servidor exibe informações de rate limit nas respostas para ajudar você a monitorar o uso.

🔧 Desenvolvimento

# Modo watch (recompila automaticamente)
npm run dev

# Compilar
npm run build

# Executar
npm start

📁 Estrutura do Projeto

pexels-mcp-server/
├── src/
│   ├── index.ts          # Servidor MCP principal
│   ├── pexels-client.ts  # Cliente HTTP para API do Pexels
│   ├── formatters.ts     # Funções de formatação de respostas
│   └── types.ts          # Tipos TypeScript
├── build/                # Código compilado
├── package.json
├── tsconfig.json
└── README.md

📄 Licença

MIT

🔗 Links Úteis

• Documentação da API do Pexels
• Documentação do MCP
• Claude Code