MCP Cybersecurity Server

Servidor MCP para análisis de vulnerabilidades CVE, integrado con la API de CIRCL Vulnerability Lookup

---

Descripción

Este proyecto implementa un servidor MCP (Model Context Protocol) especializado en análisis de vulnerabilidades de ciberseguridad. Permite a modelos de lenguaje (LLMs) consultar información de CVEs, analizar riesgos y proporcionar recomendaciones de seguridad basadas en playbooks profesionales y matrices de riesgo.

Desarrollado para: Máster en IA Aplicada a Ciberseguridad - Módulo 8 - Tarea 2 Autor: José Miguel Teba Luque Fecha: Diciembre 2025

---

Características Principales

🔧 3 Herramientas (Tools)

1. search_cve_by_id

   • Busca información detallada de un CVE específico
   • Retorna: descripción, CVSS, severidad, referencias, fechas, CWEs

2. search_cves_by_keyword

   • Busca CVEs por producto, vendor o palabra clave
   • Ideal para descubrir vulnerabilidades de tecnologías específicas

3. summarize_cve_risk

   • Análisis de riesgo orientado a equipos SOC/Blue Team
   • Incluye EPSS score, nivel de urgencia, SLAs y recomendaciones

📚 2 Recursos (Resources)

1. playbook_high_risk.md

   • Playbook operativo para gestión de vulnerabilidades críticas
   • 4 fases: Detección, Mitigación, Parcheo, Cierre
   • SLA de 4 horas, procedimientos de escalación

2. risk_matrix.json

   • Matriz de priorización de riesgos
   • 5 niveles: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL
   • Criterios basados en CVSS, EPSS y contexto del activo

🤖 1 Prompt Preconfigurado

• analyze_asset_vulnerabilities
  • Análisis completo de un activo con múltiples CVEs
  • Genera reporte ejecutivo con timeline de remediación
  • Combina tools + resources para análisis integral

---

Requisitos Previos

• Python: 3.10 o superior (recomendado 3.12+)
• Sistema Operativo: macOS, Linux, o Windows
• MCP Host: Claude Desktop, VS Code con extensión MCP, o cliente MCP compatible
• Conexión a Internet: Para consultas a la API de CIRCL

---

Instalación

1. Clonar o Descargar el Proyecto

# Navegar al directorio del proyecto
cd "/path/to/mcp-cybersecurity-server"

2. Crear Entorno Virtual

# Crear entorno virtual con Python 3.12+
python3.12 -m venv venv

# Activar entorno virtual
# En macOS/Linux:
source venv/bin/activate

# En Windows:
venv\Scripts\activate

3. Instalar Dependencias

# Actualizar pip
pip install --upgrade pip

# Instalar dependencias del proyecto
pip install -r requirements.txt

Dependencias principales:

• mcp>=1.0.0 - Framework MCP oficial de Anthropic
• httpx>=0.24.0 - Cliente HTTP async
• pydantic>=2.0.0 - Validación de datos
• python-dotenv>=1.0.0 - Gestión de variables de entorno

4. Verificar Instalación

# Verificar que MCP se instaló correctamente
python -c "import mcp; print(f'MCP version: {mcp.__version__}')"

---

Configuración

Configurar Variables de Entorno (Opcional)

# Copiar archivo de ejemplo
cp .env.example .env

# Editar .env si necesitas personalizar:
# CIRCL_API_BASE_URL=https://vulnerability.circl.lu/api
# LOG_LEVEL=INFO

Configurar Claude Desktop

1. Ubicar archivo de configuración:

   # En macOS:
   ~/Library/Application Support/Claude/claude_desktop_config.json
   
   # En Windows:
   %APPDATA%\Claude\claude_desktop_config.json
   
   # En Linux:
   ~/.config/Claude/claude_desktop_config.json
   

2. Editar el archivo y añadir la configuración del servidor:

   {
     "mcpServers": {
       "cybersecurity-server": {
         "command": "/RUTA_COMPLETA/mcp-cybersecurity-server/venv/bin/python",
         "args": [
           "-m",
           "src.server"
         ],
         "cwd": "/RUTA_COMPLETA/mcp-cybersecurity-server",
         "env": {
           "CIRCL_API_BASE_URL": "https://vulnerability.circl.lu/api"
         }
       }
     }
   }
   

   IMPORTANTE: Reemplaza /RUTA_COMPLETA/ con la ruta absoluta al directorio del proyecto.

   Ejemplo para macOS:

   {
     "mcpServers": {
       "cybersecurity-server": {
         "command": "/Users/jmteba/Library/Mobile Documents/com~apple~CloudDocs/Máster IA Ciberseguridad /Módulo 8/TAREA 2/mcp-cybersecurity-server/venv/bin/python",
         "args": ["-m", "src.server"],
         "cwd": "/Users/jmteba/Library/Mobile Documents/com~apple~CloudDocs/Máster IA Ciberseguridad /Módulo 8/TAREA 2/mcp-cybersecurity-server"
       }
     }
   }
   

3. Reiniciar Claude Desktop

4. Verificar: En Claude Desktop, deberías ver el servidor "cybersecurity-server" en la lista de servidores MCP disponibles.

---

Uso

Test 1: Búsqueda de CVE por ID

Prompt en Claude Desktop:

Busca información detallada del CVE-2024-3094

Resultado Esperado:

• Claude invoca la tool search_cve_by_id
• Retorna información completa: descripción, CVSS, severidad, referencias
• Para CVE-2024-3094 (XZ backdoor): CVSS 10.0, CRITICAL

---

Test 2: Búsqueda por Producto/Keyword

Prompt en Claude Desktop:

Busca las 5 vulnerabilidades más recientes de Apache HTTP Server

Resultado Esperado:

• Claude invoca search_cves_by_keyword con keyword="apache" y limit=5
• Retorna tabla con CVE IDs, severidad, CVSS, fechas y resúmenes

---

Test 3: Análisis de Riesgo

Prompt en Claude Desktop:

Analiza el riesgo del CVE-2024-3094 para un servidor web público de producción

Resultado Esperado:

• Claude invoca summarize_cve_risk con contexto="servidor web público"
• Retorna análisis detallado con:
  • Nivel de urgencia (CRÍTICA)
  • EPSS score y probabilidad de explotación
  • SLA de respuesta (4 horas)
  • Recomendaciones de mitigación

---

Test 4: Consultar Resource

Prompt en Claude Desktop:

Muéstrame el playbook de respuesta para vulnerabilidades críticas

Resultado Esperado:

• Claude lee el resource playbook://high_risk
• Presenta el contenido del playbook con las 4 fases

---

Test 5: Usar Prompt Preconfigurado

Prompt en Claude Desktop:

Analiza las vulnerabilidades del servidor web de producción con estos CVEs:
CVE-2024-3094, CVE-2023-44487, CVE-2023-38545

El servidor está expuesto a Internet y es de criticidad alta.

Resultado Esperado:

• Claude ejecuta el prompt analyze_asset_vulnerabilities
• Invoca múltiples tools:
  • search_cve_by_id para cada CVE
  • summarize_cve_risk para análisis de riesgo
• Lee resources:
  • risk_matrix.json para clasificación
  • playbook_high_risk.md si hay CVEs críticos
• Genera reporte completo con:
  • Resumen ejecutivo
  • Tabla priorizada de vulnerabilidades
  • Timeline de remediación
  • Recomendaciones específicas

---

Estructura del Proyecto

mcp-cybersecurity-server/
├── src/
│   ├── __init__.py
│   ├── server.py                 # Servidor MCP principal
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── cve_search.py         # Tool: search_cve_by_id
│   │   ├── cve_keyword.py        # Tool: search_cves_by_keyword
│   │   └── cve_risk.py           # Tool: summarize_cve_risk
│   ├── api/
│   │   ├── __init__.py
│   │   └── circl_client.py       # Cliente para API CIRCL
│   └── utils/
│       ├── __init__.py
│       └── formatters.py         # Utilidades de formato
├── resources/
│   ├── playbook_high_risk.md     # Resource: Playbook crítico
│   └── risk_matrix.json          # Resource: Matriz de riesgos
├── tests/                        # Tests unitarios (opcional)
│   ├── test_tools.py
│   └── test_api.py
├── config/
│   └── mcp_config.json           # Configuración del servidor
├── docs/
│   └── memoria.md                # Documentación de la práctica
├── venv/                         # Entorno virtual (no incluir en git)
├── pyproject.toml                # Metadata y dependencias
├── requirements.txt              # Dependencias pip
├── README.md                     # Este archivo
├── .gitignore
└── .env.example

---

Testing

Tests Unitarios (Opcional)

# Activar entorno virtual
source venv/bin/activate

# Ejecutar tests
pytest tests/ -v

# Con cobertura
pytest tests/ --cov=src --cov-report=html

Tests de Integración

1. Verificar servidor se inicia correctamente:

   python -m src.server
   # Debe mostrar logs sin errores
   # Ctrl+C para detener
   

2. Test desde Claude Desktop:

   • Reiniciar Claude Desktop
   • Verificar que "cybersecurity-server" aparece en la lista de servidores
   • Ejecutar los 5 tests de uso descritos arriba

---

Solución de Problemas

Error: "CVE not found"

• Causa: El CVE no existe en la base de datos de CIRCL
• Solución: Verificar el formato (CVE-YYYY-NNNN) y que el CVE está publicado

Error: "Timeout al consultar API"

• Causa: La API de CIRCL está lenta o no responde
• Solución: Reintentar después de unos segundos, verificar conexión a Internet

Error: "Tool not found" en Claude Desktop

• Causa: El servidor no está correctamente registrado
• Solución:
  1. Verificar claude_desktop_config.json
  2. Asegurar que las rutas son absolutas
  3. Reiniciar Claude Desktop

Error: "Module not found: mcp"

• Causa: Dependencias no instaladas o entorno virtual no activado
• Solución:

  source venv/bin/activate
  pip install -r requirements.txt
  

El servidor no aparece en Claude Desktop

• Solución:
  1. Verificar que el archivo de configuración está en la ubicación correcta
  2. Verificar sintaxis JSON (usar validador online)
  3. Verificar permisos de ejecución: chmod +x venv/bin/python
  4. Revisar logs de Claude Desktop (Menu > View > Toggle Developer Tools > Console)

---

Funcionalidades Avanzadas (Opcionales)

Caché de Respuestas

Para mejorar el rendimiento, puedes implementar un caché local:

# En src/api/circl_client.py
from functools import lru_cache

@lru_cache(maxsize=100)
async def cached_get_cve(cve_id: str):
    # Implementación con caché
    pass

Logging Personalizado

# En .env
LOG_LEVEL=DEBUG
LOG_FORMAT=json

Integración con SIEM

El servidor puede integrarse con sistemas SIEM para análisis automatizado de vulnerabilidades.

---

Contribuciones y Mejoras Futuras

Este proyecto es parte de un trabajo académico, pero las siguientes mejoras podrían implementarse:

• [ ] Integración con NVD (National Vulnerability Database) de NIST
• [ ] Exportación de reportes a PDF
• [ ] Tool adicional para comparar múltiples CVEs
• [ ] Resource adicional con CWEs comunes y recomendaciones
• [ ] Soporte para múltiples idiomas
• [ ] Dashboard web para visualización
• [ ] Integración con Slack/Teams para notificaciones

---

Referencias y Recursos

API Utilizada

• CIRCL Vulnerability Lookup: https://vulnerability.circl.lu/api/
• Documentación de la API: https://vulnerability.circl.lu/

Estándares de Seguridad

• CVSS v3.1: https://www.first.org/cvss/
• EPSS: https://www.first.org/epss/
• CWE Top 25: https://cwe.mitre.org/top25/
• OWASP Top 10: https://owasp.org/www-project-top-ten/

Documentación Técnica

• MCP SDK: https://github.com/anthropics/mcp
• Claude Desktop: https://claude.ai/download
• Model Context Protocol: https://modelcontextprotocol.io/

---

Licencia

Este proyecto es un trabajo académico desarrollado para el Máster en IA Aplicada a Ciberseguridad de la Universidad Católica de Murcia (UCAM) en colaboración con ENIIT y Campus Internacional de Ciberseguridad.

Uso Académico y Educativo.

---

Autor

José Miguel Teba Luque

• Máster en IA Aplicada a Ciberseguridad
• Módulo 8: Diseño y Publicación de Interfaces para Herramientas IA
• Fecha de entrega: Diciembre 2025

---