Volkern Server

Servidor MCP (Model Context Protocol) para integrar Volkern CRM con agentes de IA como Claude, GPT, y otros clientes compatibles con MCP.

Novedades v2.0.0 - Ciclo Comercial Completo

Nuevos Módulos

• Contactos: CRUD completo de contactos (personas y empresas)
• Deals/Pipeline: Crear y listar deals del pipeline de ventas
• Cotizaciones: Crear cotizaciones desde ítems del catálogo con precios, descuentos e impuestos
• Órdenes de Venta: Listar, consultar y convertir cotizaciones en órdenes de venta
• Contratos: Convertir cotizaciones aceptadas en contratos con condiciones de pago

Flujo Comercial Completo vía MCP

1. volkern_create_lead → Capturar lead
2. volkern_create_deal → Abrir oportunidad en pipeline
3. volkern_create_cotizacion → Generar cotización desde catálogo
4. volkern_create_orden_from_cotizacion → Convertir en orden de venta
5. volkern_create_contrato_from_cotizacion → Formalizar contrato

Catálogo Mejorado (v1.1.0)

• Campos personalizados: Atributos dinámicos por ítem (metros², habitaciones, idioma, etc.)
• Categorías multinivel: Organización jerárquica (Inmuebles > Oficina > Lujo)
• Etiquetas: Tags para filtrado rápido (vip, oportunidad, nuevo)
• Galería multimedia: Imágenes, video tours, documentos técnicos, tours 360°
• Precios flexibles: Pago único, recurrente o por hora con descuentos por volumen

Instalación

Opción 1: Instalación global desde NPM (Recomendado)

npm install -g volkern-mcp-server

Opción 2: Usando npx (sin instalación)

npx volkern-mcp-server

Opción 3: Desde código fuente

git clone https://github.com/volkern/mcp-server.git
cd mcp-server
npm install
npm run build

Configuración

El servidor requiere las siguientes variables de entorno:

export VOLKERN_API_KEY="tu_api_key_aqui"
export VOLKERN_API_URL="https://volkern.app/api"  # Opcional, usa este valor por defecto

Uso con Claude Desktop

Agrega la siguiente configuración a tu archivo claude_desktop_config.json:

Si instalaste con NPM (Recomendado)

{
  "mcpServers": {
    "volkern": {
      "command": "volkern-mcp",
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}

Si usas npx

{
  "mcpServers": {
    "volkern": {
      "command": "npx",
      "args": ["volkern-mcp-server"],
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}

Si instalaste desde código fuente

macOS/Linux:

{
  "mcpServers": {
    "volkern": {
      "command": "node",
      "args": ["/ruta/a/volkern-mcp-server/dist/index.js"],
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "volkern": {
      "command": "node",
      "args": ["C:\\ruta\\a\\volkern-mcp-server\\dist\\index.js"],
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}

Herramientas Disponibles (35 tools)

Contactos

Herramienta	Descripción
volkern_list_contacts	Listar contactos con filtros
volkern_get_contact	Obtener contacto por ID
volkern_create_contact	Crear un nuevo contacto
volkern_update_contact	Actualizar un contacto
volkern_delete_contact	Eliminar un contacto

Gestión de Leads

Herramienta	Descripción
volkern_list_leads	Listar leads con filtros opcionales
volkern_get_lead	Obtener detalles de un lead por ID
volkern_create_lead	Crear un nuevo lead
volkern_update_lead	Actualizar un lead existente

Citas/Appointments

Herramienta	Descripción
volkern_check_disponibilidad	Consultar horarios disponibles
volkern_list_citas	Listar citas con filtros
volkern_create_cita	Crear una nueva cita
volkern_update_cita	Actualizar una cita
volkern_cita_accion	Confirmar, cancelar o reprogramar

Servicios

Herramienta	Descripción
volkern_list_servicios	Listar servicios del catálogo
volkern_get_servicio	Obtener detalles de un servicio

Tareas

Herramienta	Descripción
volkern_create_task	Crear tarea de seguimiento
volkern_list_tasks	Listar tareas de un lead
volkern_complete_task	Marcar tarea como completada

Mensajería

Herramienta	Descripción
volkern_send_whatsapp	Enviar mensaje de WhatsApp
volkern_list_conversaciones	Listar conversaciones

Interacciones

Herramienta	Descripción
volkern_list_interactions	Listar interacciones de un lead
volkern_create_interaction	Registrar llamada, email, reunión

Notas

Herramienta	Descripción
volkern_list_notes	Listar notas de un lead
volkern_create_note	Agregar nota a un lead

Deals / Pipeline

Herramienta	Descripción
volkern_list_deals	Listar deals del pipeline con filtros
volkern_create_deal	Crear un nuevo deal

Cotizaciones

Herramienta	Descripción
volkern_create_cotizacion	Crear cotización desde ítems del catálogo

Órdenes de Venta

Herramienta	Descripción
volkern_list_ordenes_venta	Listar órdenes de venta con filtros
volkern_get_orden_venta	Obtener detalle de una orden
volkern_create_orden_from_cotizacion	Convertir cotización en orden de venta

Contratos

Herramienta	Descripción
volkern_create_contrato_from_cotizacion	Convertir cotización en contrato

Ejemplos de Uso

Crear un lead y agendar cita

Usuario: Crea un lead para Juan Pérez, email [email protected], y agenda una cita para mañana a las 10am

Agente:
1. volkern_create_lead(nombre: "Juan Pérez", email: "[email protected]")
2. volkern_check_disponibilidad(fecha: "2026-02-09")
3. volkern_create_cita(leadId: "...", fechaHora: "2026-02-09T10:00:00Z", titulo: "Reunión inicial")

Consultar disponibilidad

Usuario: ¿Qué horarios hay disponibles para el lunes?

Agente:
1. volkern_check_disponibilidad(fecha: "2026-02-10")

Crear tarea de seguimiento

Usuario: Crea un recordatorio para llamar a Juan mañana

Agente:
1. volkern_list_leads(search: "Juan")
2. volkern_create_task(leadId: "...", tipo: "llamada", titulo: "Llamar a Juan", fechaVencimiento: "2026-02-09T09:00:00Z")

Desarrollo

# Ejecutar en modo desarrollo
npm run dev

# Compilar
npm run build

# Ejecutar compilado
npm start

Troubleshooting

Error: VOLKERN_API_KEY not set

Asegúrate de configurar la variable de entorno antes de iniciar el servidor.

Error 401: No autorizado

Verifica que tu API key tenga los permisos necesarios en Volkern (Configuración → API Keys).

Error 409: Conflicto de horario

El slot solicitado ya está ocupado. Consulta disponibilidad con volkern_check_disponibilidad.

Licencia

MIT