# MCP Cybersecurity Server
**Servidor MCP para análisis de vulnerabilidades CVE, integrado con la API de CIRCL Vulnerability Lookup**
[](https://www.python.org/downloads/)
[](https://github.com/anthropics/mcp)
[]()
---
## 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
```bash
# Navegar al directorio del proyecto
cd "/path/to/mcp-cybersecurity-server"
```
### 2. Crear Entorno Virtual
```bash
# 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
```bash
# 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
```bash
# Verificar que MCP se instaló correctamente
python -c "import mcp; print(f'MCP version: {mcp.__version__}')"
```
---
## Configuración
### Configurar Variables de Entorno (Opcional)
```bash
# 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**:
```bash
# 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:
```json
{
"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**:
```json
{
"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)
```bash
# 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**:
```bash
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**:
```bash
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:
```python
# 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
```bash
# 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
---
