Wireshark MCP

Servidor MCP basado en FastMCP que expone herramientas de captura, análisis, detección de amenazas e informes de Wireshark/tshark para agentes de IA y pruebas locales.

Tabla de contenidos

• Requisitos previos

• Inicio rápido

• Ejecución del servidor

• Uso de herramientas (ejemplos)

• Herramientas disponibles (resumen)

• Solución de problemas

• Contribución

Requisitos previos

• Python: 3.8+ (se recomienda 3.11)

• Wireshark (para la CLI tshark). En Windows, instale Wireshark + Npcap.

• Permisos: La captura de paquetes generalmente requiere privilegios elevados en Windows.

Asegúrese de que tshark esté instalado o disponible en una ruta común (por ejemplo, C:\Program Files\Wireshark\tshark.exe). El proyecto incluye un TsharkWrapper que busca en PATH y en ubicaciones comunes de Windows.

Related MCP server: wireshark-mcp

Inicio rápido

Clone el repositorio y cree un entorno virtual.

Windows (PowerShell):

git clone <your-repo-url>
cd Wireshark_MCP
python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Linux / macOS:

git clone <your-repo-url>
cd Wireshark_MCP
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Opcional: copie config.example.json a config.json y edite cualquier configuración específica del proyecto.

Ejecución del servidor

Existen dos modos comunes:

• Transporte stdio: diseñado para la integración directa con clientes compatibles con MCP (por ejemplo, integraciones de Wireshark/IDE). Este es el valor predeterminado al ejecutar el paquete principal.

• Transporte http: expone el servidor MCP a través de una API HTTP (útil para pruebas o clientes externos).

Recomendado (Windows): utilice el ejecutor incluido que activa el venv e inicia el servidor:

.\run_server.ps1

Ejecución manual (stdio):

.\venv\Scripts\Activate.ps1
python -m wireshark_mcp.server

Iniciar con transporte HTTP (script de ejemplo). Cree run_network_server.py con:

from wireshark_mcp import server

# Starts FastMCP with HTTP transport on 127.0.0.1:8765
server.main().run(transport="http", host="127.0.0.1", port=8765)

Ejecútelo:

python run_network_server.py

Cuando se inicie con transporte HTTP, verá registros de Uvicorn como:

INFO:     Uvicorn running on http://127.0.0.1:8765 (Press CTRL+C to quit)

Uso de herramientas (ejemplos)

Para el desarrollo y las pruebas, recomendamos llamar a los módulos de herramientas directamente (estos devuelven objetos de Python estructurados). Las funciones decoradas con MCP del servidor devuelven cadenas serializadas para el transporte MCP.

Ejemplos de Python (dentro del venv activado):

# List network interfaces (preferred for testing)
from wireshark_mcp.tools import capture
print(capture.list_network_interfaces())

# Analyze a PCAP file
from wireshark_mcp.tools import analysis
print(analysis.analyze_pcap("/path/to/capture.pcap"))

# Detect threats in a PCAP
from wireshark_mcp.tools import threat_detection
print(threat_detection.detect_threats("/path/to/capture.pcap"))

Si desea probar las herramientas MCP a través de la capa del servidor (los clientes MCP llamarán a estas), el servidor expone las herramientas con el mismo nombre. Ejemplo (nota: estas devuelven cadenas):

from wireshark_mcp import server
print(server.list_network_interfaces())  # returns serialized string

Herramientas disponibles (resumen)

Captura

• list_network_interfaces — listar dispositivos de captura disponibles

• capture_packets — capturar paquetes en vivo (interfaz, duración, packet_count, bpf_filter)

Análisis

• analyze_pcap — análisis completo de pcap

• extract_dns_queries — consultas DNS y dominios sospechosos

• extract_ip_addresses — extracción de IP y patrones de tráfico

• get_protocol_statistics — distribución de protocolos

Detección de amenazas

• detect_threats — extracción de IOC y puntuación de riesgo

• analyze_malicious_domains — análisis profundo de dominios

• analyze_suspicious_ips — comprobaciones de reputación de IP

• detect_attack_patterns — detección de firmas/patrones

Solución de problemas

• analyze_connectivity_issue — diagnóstico de conectividad de destino

• analyze_vpn_behavior — comparación entre VPN y no VPN

• analyze_latency_and_retransmissions — pérdida de paquetes y retransmisiones

• analyze_web_performance — análisis de tráfico de aplicaciones web

Informes

• generate_analysis_report — generación de informes completos

• generate_security_report — informe centrado en la seguridad

Consulte wireshark_mcp/server.py para ver las firmas exactas de las herramientas y las cadenas de documentación.

Solución de problemas

• tshark no encontrado: instale Wireshark y asegúrese de que tshark esté en PATH o presente en la carpeta de instalación predeterminada. El TsharkWrapper incluido busca en ubicaciones comunes de Windows cuando PATH no contiene tshark.

• Errores de permiso al capturar en Windows: asegúrese de que Npcap esté instalado y ejecute PowerShell como Administrador.

• Si una herramienta devuelve failed con una cadena de error, ejecute la función equivalente en wireshark_mcp.tools directamente para inspeccionar las excepciones.

Registros: El servidor utiliza el registro estándar; verifique la salida de la consola donde inició el servidor para obtener detalles.

Contribución

• Realice cambios en una rama de características, agregue pruebas cuando corresponda y abra una solicitud de extracción (pull request).

• Mantenga estables las API públicas en wireshark_mcp.tools; las funciones decoradas del server son para la exposición a MCP.

Licencia

Agregue su archivo de licencia preferido (por ejemplo, LICENSE) antes de publicar en GitHub.

Si lo desea, también puedo:

• crear un CONTRIBUTING.md breve,

• agregar scripts de ejemplo en una carpeta scripts/ (ejecutor HTTP, fragmentos de prueba rápida), o

• abrir una rama Git local y confirmar estos cambios por usted.

Seguridad y calidad del código

El proyecto se escanea regularmente con una herramienta de análisis estático (SonarQube) para detectar problemas de seguridad, confiabilidad y mantenibilidad. Las capturas de pantalla a continuación se tomaron del escaneo más reciente y se incluyen aquí como evidencia de respaldo para las partes interesadas.

Nota: las capturas de pantalla muestran el estado del análisis en el momento en que se tomaron. La fuente autorizada es la página del proyecto SonarQube; incluya ese enlace si publica estos artefactos públicamente.

Referencias de figuras (coloque los archivos de imagen en docs/images/):

• docs/images/sonarqube_result.jpeg — resumen del proyecto / estado general (SonarQube)

• docs/images/snyk_result.jpeg — resumen del escaneo de dependencias/seguridad (Snyk)

Figura 1 — Resumen del proyecto SonarQube (Aprobado / sin problemas abiertos de seguridad o confiabilidad en el momento del escaneo).

Figura 2 — Salida del escaneo Snyk que ilustra las comprobaciones y los recuentos de dependencias/seguridad.

Cómo agregar las imágenes a este repositorio:

1. Cree la carpeta docs/images/ en la raíz del repositorio.

2. Guarde las capturas de pantalla como sonar_project.png y sonar_summary.png en esa carpeta.

3. Confirme y envíe las imágenes junto con el README:

git add docs/images/sonar_project.png docs/images/sonar_summary.png README.md
git commit -m "docs: add SonarQube screenshots to README"
git push origin <your-branch>

Si lo desea, cargue las capturas de pantalla aquí (o proporcione acceso a la URL del proyecto SonarQube) y las agregaré y confirmaré por usted.