Freepik MCP

🚀 Servidor MCP para una integración fluida con la API de Freepik

🎯 ¿Qué es esto?

Un servidor del Protocolo de Contexto de Modelo (MCP) que conecta tus asistentes de IA (Claude, Cursor, etc.) directamente con las potentes APIs de Freepik. Genera, busca y gestiona contenido visual sin salir de tu flujo de trabajo de IA.

🛠️ ¿Qué herramientas están disponibles?

• 🎨 Búsqueda y descarga de iconos - Encuentra y descarga iconos en múltiples formatos

• 📁 Gestión de recursos - Accede y gestiona contenido multimedia

• 🤖 Clasificación de imágenes por IA - Clasifica y analiza imágenes automáticamente

• 🖼️ Generación de imágenes - Crea imágenes personalizadas usando Mystic AI

📋 Requisitos previos

Antes de empezar, asegúrate de tener:

• Python 3.12+ instalado

• uv gestor de dependencias (instálalo aquí)

• Clave de API de Freepik (consíguela aquí)

🚀 Instalación

1. Clonar y navegar

git clone <REPOSITORY_URL>
cd freepik-mcp

2. Instalar usando Makefile

# Install dependencies
make install

# Verify installation
make version

3. Configurar tu clave de API

echo "FREEPIK_API_KEY=your_api_key_here" > .env

💡 Obtén tu clave de API en: freepik.com/api

⚙️ Configuración para asistentes de IA

Para Claude Desktop o Cursor en Linux

Añade esto a tu archivo config.json:

⚠️ Para usuarios de Windows: Si estás en Windows, necesitas usar WSL (Subsistema de Windows para Linux) para ejecutar este servidor MCP.

{
  "mcpServers": {
    "freepik-fastmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/FULL/PATH/TO/freepik-mcp",
        "main.py"
      ],
      "env": {
        "FREEPIK_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}

🔧 Pasos de configuración importantes

1. Encuentra tu ruta completa:

   pwd
   # Copy the output and replace /FULL/PATH/TO/ in the config

2. Reemplaza con tu clave de API:

   • Consíguela en freepik.com/api

   • Reemplaza your_actual_api_key_here

🏃♂️ Inicio rápido

# Development mode (auto-reload)
make dev

# Production mode
make run

# Check code quality
make lint

# Format code
make format

# Clean temporary files
make clean

# See all commands
make help

🤝 Contribución

¡Damos la bienvenida a las contribuciones! Por favor, sigue estas directrices:

📝 Convención de commits

Este proyecto utiliza Conventional Commits. Formatea tus commits como:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Tipos:

• feat: Nueva funcionalidad

• fix: Corrección de errores

• docs: Cambios en la documentación

• style: Cambios en el estilo del código (formato, etc.)

• refactor: Refactorización de código

• test: Añadir o actualizar pruebas

• chore: Tareas de mantenimiento

Ejemplos:

feat(icons): add search filtering by category
fix(api): resolve authentication timeout issue
docs(readme): update installation instructions
refactor(mystic): improve error handling logic

🔄 Flujo de trabajo de contribución

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad: git checkout -b feat/amazing-feature

3. Haz commit usando el formato convencional: git commit -m "feat: add amazing feature"

4. Envía (push) a tu rama: git push origin feat/amazing-feature

5. Abre un Pull Request

📚 Comandos de desarrollo

🛡️ Seguridad

• ⚠️ Nunca hagas commit de tu clave de API

• ✅ Usa archivos .env para datos sensibles

• ✅ El archivo .env está en .gitignore

📖 Documentación de la API

Para información detallada de la API:

• Documentación de la API de Freepik

🆘 Solución de problemas

Problemas comunes:

1. "Command not found" → Instala el gestor de dependencias uv

2. "Invalid API Key" → Comprueba tu clave en freepik.com/api

3. "Path not found" → Verifica la ruta completa en tu configuración

4. "Connection refused" → Asegúrate de que el servidor se esté ejecutando con make dev

¿Sigues teniendo problemas? Abre un issue en GitHub con:

• Tu sistema operativo y versión de Python

• Mensaje de error completo

• Archivo de configuración (sin la clave de API)

¿Listo para crear contenido increíble con IA? 🎨✨