jithinjk/mcp-server-ebpf-observability

eBPF Observability MCP Server

A production-ready Model Context Protocol (MCP) server that provides unified observability for eBPF-based tools in Kubernetes environments. Optimized for OrbStack VMs and designed to work with Cilium, Falco, and Calico to deliver comprehensive container networking, security monitoring, and policy management through a single MCP interface.

Future Integration Possibilities: This server is designed with extensibility in mind and could potentially integrate with enterprise networking and security platforms in future releases.

🔒 Security-First Design

This MCP server has been security-hardened against all known MCP vulnerabilities identified in recent security research:

• ✅ Network Security: Binds to localhost only (never 0.0.0.0) - prevents "NeighborJack" attacks
• ✅ Command Injection Prevention: Comprehensive input sanitization and subprocess security
• ✅ Access Control: Read-only operations with namespace and verb restrictions
• ✅ Rate Limiting: Protection against abuse and DoS attacks
• ✅ Audit Logging: Complete security event logging and monitoring

Features

• OrbStack VM Management - Start, stop, and execute commands in VMs
• Platform Detection - Automatic OrbStack and Kubernetes cluster detection
• Unified eBPF Interface - Single API for Cilium, Falco, and Calico
• Custom eBPF Programs - 🆕 Kernel-space tracing for process, network, file, and syscall monitoring
• Real-time Security Events - Live security monitoring with Falco + custom eBPF
• Network Policy Management - Deploy and manage network policies
• Deep Network Observability - Traffic analysis via Cilium Hubble + kernel-level tracing
• Security Context Analysis - Pod and container security assessment
• Production Security - Input validation, rate limiting, audit logging

🔬 NEW: Custom eBPF Programs - Advanced kernel-space observability with:

• Process Monitoring - Real-time process creation/termination tracking
• Network Tracing - Kernel-level TCP/UDP connection monitoring
• File Access Tracking - File system access patterns and changes
• Syscall Monitoring - Security-relevant system call detection

Note: This server requires OrbStack with an Ubuntu VM and kubectl access to a Kubernetes cluster with eBPF tools deployed.

Quick Start

Using uvx (recommended)

uvx mcp-server-ebpf-observability

Using pip

pip install mcp-server-ebpf-observability
python -m mcp_server_ebpf_observability

From source

git clone https://github.com/jithinjk/mcp-server-ebpf-observability.git
cd mcp-server-ebpf-observability
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
python src/mcp_server.py

Installation

Requirements

• OrbStack with Ubuntu VM running
• Python 3.10+
• kubectl configured for your cluster
• Kubernetes cluster with eBPF tools (Cilium, Falco, Calico)

Verify Prerequisites

# Check OrbStack
orb list

# Check kubectl access
kubectl cluster-info

# Check eBPF tools (optional - server can detect)
kubectl get pods -n kube-system | grep -E "(cilium|falco|calico)"

API

Resources

• ebpf://cluster/status - Overall eBPF tool status and cluster information
• ebpf://cilium/status - Cilium networking status and configuration
• ebpf://falco/events - Recent Falco security events and alerts
• ebpf://network/policies - Current network policies across all tools
• ebpf://demo/status - Demo environment status and workloads

Tools

• detect_platforms

  • Detect available platforms (OrbStack, kubectl, minikube, kind, k3s)
  • Input: None
  • Returns platform availability and cluster information

• manage_orbstack_vms

  • Manage OrbStack VMs (list, start, stop, exec commands)
  • Inputs: action (string), vm_name (string, optional), command (string, optional)
  • Supports OrbStack VM lifecycle management

• check_security_events

  • Get recent security events from Falco
  • Inputs: namespace (string, optional), limit (number, optional)
  • Returns security alerts and compliance violations

• get_pod_security_context

  • Analyze security context of pods
  • Inputs: namespace (string), pod_name (string, optional)
  • Returns security analysis and recommendations

• analyze_network_traffic

  • Analyze network traffic patterns with Cilium Hubble
  • Inputs: namespace (string, optional), pod (string, optional)
  • Returns traffic patterns and performance metrics

• trace_network_connections

  • Trace active network connections
  • Inputs: namespace (string, optional), protocol (string, optional)
  • Returns connection details and network topology

• deploy_network_policy

  • Generate and optionally deploy network policies
  • Inputs: namespace (string), policy_type (string), apply (boolean, optional)
  • Creates Kubernetes NetworkPolicy resources

🆕 Custom eBPF Tools

• initialize_custom_ebpf

  • Initialize and start custom kernel-space eBPF programs
  • Inputs: None
  • Returns initialization status and loaded programs

• get_custom_ebpf_status

  • Get status and requirements for custom eBPF programs
  • Inputs: None
  • Returns availability, requirements, and monitoring stats

• get_custom_ebpf_events

  • Get events from custom eBPF programs (process/network/file/syscall)
  • Inputs: event_type (string), limit (number)
  • Returns kernel-level tracing events with process context

• compile_custom_ebpf

  • Compile custom eBPF programs from source
  • Inputs: force_recompile (boolean, optional)
  • Returns compilation status and build artifacts

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

Using uvx (recommended)

{
  "mcpServers": {
    "ebpf-observability": {
      "command": "uvx",
      "args": ["mcp-server-ebpf-observability"]
    }
  }
}

Using pip

{
  "mcpServers": {
    "ebpf-observability": {
      "command": "python3",
      "args": ["-m", "mcp_server_ebpf_observability"],
      "env": {
        "PATH": "/Users/username/.orbstack/bin:${PATH}"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "ebpf-observability": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-v", "/Users/username/.kube:/root/.kube:ro",
        "-v", "/Users/username/.orbstack:/root/.orbstack:ro",
        "mcp-server-ebpf-observability"
      ]
    }
  }
}

Usage with VS Code

For quick installation, click the installation buttons below:

Or manually add to your VS Code MCP settings:

{
  "mcpServers": {
    "ebpf-observability": {
      "command": "uvx",
      "args": ["mcp-server-ebpf-observability"]
    }
  }
}

Examples

Platform Detection

Claude: "What platforms are available in my environment?"
Claude: "Detect my current Kubernetes setup"
Claude: "Show me my OrbStack VM status"

Security Monitoring

Claude: "Check recent security events in my cluster"
Claude: "Analyze the security context of pods in the demo namespace"
Claude: "What security violations have occurred in the last hour?"

Network Operations

Claude: "Show me the current network policies"
Claude: "Trace network connections in the demo namespace"
Claude: "Analyze traffic patterns for the frontend service"
Claude: "Deploy a network policy to isolate the database"

OrbStack VM Management

Claude: "List all my OrbStack VMs"
Claude: "Start my ubuntu VM"
Claude: "Execute 'kubectl get pods' in my ubuntu VM"
Claude: "Check the status of my kubernetes cluster via OrbStack"

🆕 Custom eBPF Kernel Tracing

Claude: "Initialize the custom eBPF kernel tracing programs"
Claude: "Show me recent process events from kernel monitoring"
Claude: "What network connections are being made at the kernel level?"
Claude: "Track file access patterns in the last 5 minutes"
Claude: "Are there any suspicious system calls or privilege escalations?"
Claude: "Compile the custom eBPF programs and check their status"

Architecture

graph TB
    Claude[Claude Desktop] -->|stdio/HTTP| MCP[eBPF MCP Server]
    MCP -->|orb -m ubuntu kubectl| OrbStack[OrbStack Ubuntu VM]
    MCP -->|orb list/start/stop| OrbVM[OrbStack VM Management]
    OrbStack --> K8s[Kubernetes Cluster]
    
    subgraph "eBPF Tools in OrbStack"
        K8s --> Cilium[Cilium + Hubble]
        K8s --> Falco[Falco Security]
        K8s --> Calico[Calico Network]
    end
    
    subgraph "🆕 Custom eBPF Programs"
        MCP --> CustomeBPF[Custom eBPF Manager]
        CustomeBPF --> ProcessMon[Process Monitor]
        CustomeBPF --> NetTracer[Network Tracer]
        CustomeBPF --> FileMon[File Monitor]
        CustomeBPF --> SyscallMon[Syscall Tracer]
        ProcessMon --> Kernel[Linux Kernel]
        NetTracer --> Kernel
        FileMon --> Kernel
        SyscallMon --> Kernel
    end
    
    subgraph "MCP Capabilities"
        MCP --> Resources[Resources: cluster status, events, policies]
        MCP --> Tools[Tools: security analysis, network tracing]
        MCP --> Security[Security: validation, rate limiting, audit]
    end

Security

This server implements comprehensive security controls:

• Input Validation: All kubectl commands are sanitized and validated
• Access Control: Namespace and operation allowlisting
• Rate Limiting: 50 requests/minute protection
• Audit Logging: Complete security event tracking
• Resource Limits: Timeout and memory usage protection
• MCP Security Best Practices: Compliant with latest MCP security guidelines

See for complete details.

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
python -m pytest tests/

# Run specific test suites
python tests/test_security_validation.py
python tests/test_orbstack_integration.py

Building and Publishing

# Build package
python -m build

# Install locally
pip install -e .

# Run server
python -m mcp_server_ebpf_observability

Project Structure

mcp-server-ebpf-observability/
├── src/                     # Source code
│   ├── mcp_server.py       # Main stdio MCP server  
│   ├── mcp_http_server.py  # HTTP/StreamableHTTP MCP server
│   ├── custom_ebpf_manager.py  # 🆕 Custom eBPF program manager
│   └── main.py             # CLI entry point
├── ebpf/                    # 🆕 Custom eBPF programs
│   ├── programs/           # eBPF C source files (.bpf.c)
│   ├── headers/            # Common headers and definitions
│   ├── build/              # Compiled programs (.bpf.o)
│   └── Makefile            # Build system
├── config/                  # Configuration examples
├── tests/                   # Test suites
├── docs/                    # Documentation
├── k8s/                     # Kubernetes manifests
├── scripts/                 # Helper scripts
├── pyproject.toml          # Package configuration
├── Dockerfile              # Container image
└── requirements.txt        # Dependencies

Documentation

• - Security features and best practices
• - System design and components
• - Kernel-space eBPF programs
• - Complete project overview

Comparison: Cilium vs Falco vs Calico

Contributing

We welcome contributions! Please see our for details on:

• How to report issues and suggest features
• Setting up your development environment
• Code style and testing requirements
• Submitting pull requests
• Security considerations

For quick contribution:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure security compliance
5. Submit a pull request

License

Apache License 2.0 - see file for details.

Built with ❤️ for the eBPF and cloud-native community