eBPF MCP

Un servidor MCP seguro para eBPF, diseñado para integración con IA, introspección del kernel y automatización.

Documentación

🐝 ebpf-mcp: Control eBPF compatible con IA mediante Model Context Protocol

Un servidor MCP seguro, mínimo y con esquema forzado para eBPF — diseñado específicamente para integración con IA, introspección del kernel y automatización.

🧠 ¿Qué es esto?

ebpf-mcp es un servidor Model Context Protocol (MCP) seguro que expone un conjunto mínimo de herramientas estructuradas para interactuar con eBPF — optimizado para control seguro de IA, agentes de automatización y operadores humanos.

Permite cargar, adjuntar, inspeccionar y transmitir programas eBPF — todo mediante contratos estrictos de JSON Schema validados en tiempo de ejecución. Sin APIs REST, sin escapes de shell y sin envoltorios de bpftool.

🚀 Inicio rápido

📦 Instalación de una línea

# Install ebpf-mcp server
curl -fsSL https://raw.githubusercontent.com/sameehj/ebpf-mcp/main/install.sh | sudo bash

# Start the service (runs on port 8080 by default)
sudo systemctl start ebpf-mcp
sudo systemctl enable ebpf-mcp

# Get your auth token
cat /etc/ebpf-mcp-token

# Check service status
sudo systemctl status ebpf-mcp

# View logs if needed
sudo journalctl -u ebpf-mcp -f

Para entornos aislados o de desarrollo:

git clone https://github.com/sameehj/ebpf-mcp.git
cd ebpf-mcp
sudo ./install.sh v1.0.2

🧪 Probar la instalación

# Run the complete test suite
cd scripts/
chmod +x test-ebpf-mcp-server.sh
./test-ebpf-mcp-server.sh <your-token>

Si no se proporciona un token, el script lo solicitará de forma interactiva.

🤖 Integración con Claude CLI

Una vez instalado, conecta Claude a tu servidor eBPF (se ejecuta en el puerto 8080):

# Add MCP server to Claude CLI
claude mcp add ebpf http://localhost:8080/mcp \
  -t http \
  -H "Authorization: Bearer $(cat /etc/ebpf-mcp-token)"

# Start Claude with eBPF tools
claude --debug

# Optional: Test with MCP Inspector (requires Node.js)
npx @modelcontextprotocol/inspector http://localhost:8080/mcp

📘 Tutoriales

¿Buscas comenzar en entornos específicos o con Cursor IDE?

🧰 Guía de configuración de VirtualBox

Aprende a configurar y ejecutar ebpf-mcp dentro de una máquina virtual de VirtualBox, con reenvío de puertos, acceso SSH y consejos prácticos.

🖥️ Integración de Cursor IDE + eBPF-MCP

Guía paso a paso para ejecutar el servidor eBPF MCP con Cursor IDE para observabilidad impulsada por IA.

Ejemplos de prompts:

> Get system info and kernel version
> Load and attach a kprobe program to monitor sys_execve
> Show me all active eBPF programs and their types
> Stream events from ringbuffer maps for 10 seconds
> Trace kernel errors for the next 5 seconds

📥 Opciones de instalación

Método	Comando	Caso de uso
Una línea	`curl ... \| sudo bash`	Sistemas de producción
Manual	`git clone && sudo ./install.sh`	Desarrollo/aislado
Compilar desde el código fuente	`make build`	Modificaciones personalizadas
Docker	Próximamente	Entornos contenedorizados

🔧 Conjunto de herramientas mínimo

Cada herramienta está diseñada para ser validable por esquema, orquestable por IA y segura por defecto. Cubren más del 80% de los flujos de trabajo reales de observabilidad y control.

Nombre de la herramienta	Estado	Descripción	Capacidades requeridas
`info`	✅	Introspección del sistema: kernel, arquitectura, BTF	`CAP_BPF` o ninguno (solo lectura)
`load_program`	✅	Cargar y validar archivos `.o` (compatible con CO-RE)	`CAP_BPF` o `CAP_SYS_ADMIN`
`attach_program`	✅	Adjuntar programa a hooks XDP, kprobe, tracepoint	Depende del tipo (p. ej. `CAP_NET_ADMIN` para XDP)
`inspect_state`	✅	Listar programas, mapas, enlaces y metadatos de herramientas	`CAP_BPF` (solo lectura)
`stream_events`	✅	Transmitir eventos desde mapas ringbuf/perfbuf	`CAP_BPF` (solo lectura)
`trace_errors`	✅	Monitorear tracepoints del kernel para condiciones de error	`CAP_BPF` (solo lectura)

Todas las herramientas devuelven salida JSON estructurada — lista para IA, compatible con streaming y validada por esquema.

🔍 Consulta docs/TOOL_SPECS.md para definiciones completas de esquemas.

🚀 Lo que puedes hacer

✅ Consultar versión del kernel, arquitectura y disponibilidad de BTF
✅ Cargar programas desde disco o base64 en línea con BTF opcional
✅ Adjuntar a sistemas en vivo con restricciones de tipo seguro
✅ Inspeccionar objetos fijados, versión del kernel, estado del verificador
✅ Transmitir eventos en tiempo real con filtrado por pid/comm/cpu
✅ Rastrear errores del kernel y anomalías del sistema
✅ Descubrir herramientas disponibles y sus esquemas
✅ Integrar con Claude, Ollama o clientes compatibles con MCP

🛡️ Modelo de seguridad

Capa	Controles
Ejecución de eBPF	Verificador del kernel + límites de recursos
Sistema de archivos	Sin shell, sin exec, rutas validadas
Aislamiento en tiempo de ejecución	Limpieza por sesión, entradas estrictas
Seguridad de IA	Esquemas conscientes de capacidades + límites de salida
Autenticación	Token Bearer + listo para HTTPS

🧼 Todos los recursos se limpian automáticamente cuando un cliente se desconecta (no se requiere descarga/desconexión manual a menos que esté fijado).

📦 Estructura del proyecto

.
├── cmd/              # MCP server + CLI client
├── internal/         # Core logic: eBPF, tools, kernel adapters
├── pkg/types/        # JSON schema bindings + shared types
├── docs/             # Tool specs, design notes, schemas
├── scripts/          # Install script + test suite
└── schemas/          # JSON Schema files for each tool

🧠 Notas avanzadas de diseño

✅ Gestión del ciclo de vida

🔒 Sin desconexión manual: Los enlaces se cierran automáticamente a menos que estén fijados
🧹 Limpieza automática: Los descriptores de archivo y la memoria se liberan al desconectarse
📎 Fijación: Rutas de fijación opcionales (/sys/fs/bpf/...) para mapas/programas/enlaces

🤖 Compatibilidad con herramientas de IA

Todas las herramientas están estrictamente tipadas con esquemas publicados y devuelven salida JSON estructurada
Listo para IA: Sin necesidad de análisis — integración directa con modelos de lenguaje
Compatible con streaming: Flujos de datos en tiempo real para flujos de trabajo de observabilidad
Las respuestas incluyen:
- tool_version
- verifier_log (para depuración)
- Estructurado error con context

🔗 Extensibilidad

Futuras herramientas opcionales:

pin_object / unpin_object
detach_link
map_batch_op

Estas se omiten por defecto por seguridad y simplicidad.

📚 Referencias

🧪 Consulta scripts/test-ebpf-mcp-server.sh para la suite de validación completa.

Arquitectura básica:

Claude / Ollama / AI Client
          ↓
     MCP JSON-RPC
          ↓
   ebpf-mcp server
          ↓
     Kernel APIs

📜 Licencias

Componente	Licencia
`internal/ebpf/`	GPL-2.0
Todo lo demás	Apache-2.0

✉️ Contacto

📬 GitHub – sameehj/ebpf-mcp 🛠 ¡Contribuciones, problemas y PRs bienvenidos!

Estructurado. Seguro. Nativo de esquemas. ebpf-mcp lleva eBPF a la era de la IA.