NetPulse 🌐

An MCP server that exposes live network monitoring data as Resources and diagnostic capabilities as Tools, letting AI assistants query network health conversationally.

NetPulse bridges the gap between traditional network monitoring and AI-powered operations. It implements the Model Context Protocol (MCP) to give AI assistants like Claude real-time access to network telemetry — device status, interface metrics, latency measurements, bandwidth utilization, and active alerts — all through a clean, structured API.

---

Architecture

graph TB
    subgraph "AI Layer"
        Claude["Claude Desktop / MCP Client"]
    end

    subgraph "NetPulse MCP Server"
        Server["server.py<br/>FastMCP"]
        Resources["Resources<br/>6 data endpoints"]
        Tools["Tools<br/>6 diagnostic actions"]
        Prompts["Prompts<br/>3 workflow templates"]
        Sim["Network Simulator<br/>7 virtual devices"]
        Metrics["Prometheus Exporter<br/>/metrics"]
    end

    subgraph "Observability Stack"
        Prom["Prometheus"]
        Graf["Grafana"]
    end

    Claude <-->|MCP Protocol| Server
    Server --> Resources
    Server --> Tools
    Server --> Prompts
    Resources --> Sim
    Tools --> Sim
    Sim --> Metrics
    Metrics --> Prom
    Prom --> Graf

    style Claude fill:#6B48FF,color:#fff
    style Server fill:#0EA5E9,color:#fff
    style Sim fill:#10B981,color:#fff
    style Graf fill:#F59E0B,color:#fff

Data Flow

1. Network Simulator generates realistic, time-varying metrics for 7 virtual devices
2. MCP Resources expose read-only telemetry data (device status, interfaces, latency, bandwidth, topology, alerts)
3. MCP Tools provide executable diagnostics (ping, traceroute, interface check, config viewer, baseline comparison, interface restart)
4. MCP Prompts offer guided workflows (health briefing, troubleshooting, capacity planning)
5. Prometheus + Grafana provide visual dashboards alongside the AI interface

---

Quick Start

1. Clone the repository

git clone https://github.com/yourusername/netpulse.git
cd netpulse

2. Launch the full stack

docker compose up -d

This starts:

• NetPulse MCP Server on port 8080 (SSE transport)
• Prometheus on port 9091
• Grafana on port 3000 (login: admin / netpulse)

3. Connect Claude Desktop

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "netpulse": {
      "command": "python",
      "args": ["-m", "netpulse.server"],
      "cwd": "/path/to/netpulse"
    }
  }
}

Or for SSE transport:

{
  "mcpServers": {
    "netpulse": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Now ask Claude: "Give me a network health summary" — and watch it query real telemetry!

---

MCP Interface Reference

Resources (Read-Only Data)

URI	Description
netpulse://devices/status	Status of all 7 monitored devices with CPU, memory, temperature
netpulse://interfaces/{device}	Interface metrics for a specific device
netpulse://latency/report	Latency matrix between all connected endpoints
netpulse://bandwidth/top-talkers	Top 10 bandwidth consumers
netpulse://topology/map	Network topology as nodes + edges with health status
netpulse://alerts/active	Currently firing alerts with severity

Tools (Executable Actions)

Tool	Description	Key Parameters
ping_device	Ping a device and get RTT stats	target, count
run_traceroute	Trace network path to destination	target, max_hops
check_interface	Detailed interface diagnostics	device, interface
get_device_config	View device running configuration	device, section
compare_baseline	Compare current vs historical baseline	device, metric, window
restart_interface	Bounce an interface (requires confirmation)	device, interface, confirm

Prompts (Workflow Templates)

Prompt	Description	Arguments
network_health_summary	NOC morning briefing workflow	None
troubleshoot_connectivity	Guided connectivity diagnosis	source, destination
capacity_planning	Bandwidth analysis and projections	None

---

Configuration

Environment Variables

Variable	Default	Description
NETPULSE_HOST	0.0.0.0	Server bind address
NETPULSE_PORT	8080	MCP server port
NETPULSE_TRANSPORT	stdio	Transport mode (stdio or sse)
NETPULSE_LOG_LEVEL	INFO	Logging level
NETPULSE_POLL_INTERVAL	30	Metric polling interval (seconds)

Device Inventory

Edit src/netpulse/config/devices.yaml to customize the simulated network topology. The default includes 7 devices across 2 data centers and a branch office.

Thresholds

Edit src/netpulse/config/thresholds.yaml to adjust alerting thresholds for CPU, memory, latency, packet loss, bandwidth, and temperature.

---

Fault Injection (Demo)

Inject faults to demonstrate AI-driven incident detection:

# Take down the WAN link
python -m netpulse.simulators.fault_injector --scenario link_down

# Spike CPU on the core router
python -m netpulse.simulators.fault_injector --scenario cpu_spike

# Simulate interface flapping
python -m netpulse.simulators.fault_injector --scenario interface_flap

# Take down a device
python -m netpulse.simulators.fault_injector --scenario device_down

# Saturate bandwidth
python -m netpulse.simulators.fault_injector --scenario bandwidth_saturation

Then ask Claude: "Are there any network issues right now?"

---

Development

Local Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

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

# Run the server locally (stdio mode)
python -m netpulse.server

Running Tests

pytest --cov=netpulse --cov-report=term-missing

Code Quality

# Linting
ruff check src/ tests/

# Type checking
mypy src/netpulse/

---

Simulated Network Topology

          ┌─────────────┐          ┌─────────────┐
          │ core-rtr-01  │◄────────►│ core-rtr-02  │
          │  10.0.0.1    │ 10Gbps  │  10.0.0.2    │
          │  Data Ctr A  │backbone │  Data Ctr B  │
          └──┬──────┬────┘          └──────┬───────┘
             │      │                      │
        10G  │      │ 100M            10G  │
             │      │                      │
     ┌───────┴──┐   │              ┌───────┴──┐
     │dist-sw-01│   │              │dist-sw-02│
     │ 10.0.1.1 │   │              │ 10.0.1.2 │
     └─────┬────┘   │              └──────────┘
           │        │
      1G   │        │
           │        │
     ┌─────┴────┐   │         ┌───────────┐
     │edge-fw-01│   └────────►│ wan-rtr-01 │
     │ 10.0.2.1 │     WAN    │  10.0.4.1  │
     └──────────┘             └──────┬─────┘
                                     │ 1G
                              ┌──────┴──────┐
                              │access-sw-01 │
                              │  10.0.3.1   │
                              │ Branch Off 1│
                              └─────────────┘

---

Author

Hind Boukhairat — IoT dev specializing in network monitoring and AIOps, transitioning into AI Integration Engineering. Holder of two MCP certifications from Anthropic/Skilljar (Introduction + Advanced Topics).

NetPulse is part of a portfolio showcasing the intersection of telecom/network operations and AI orchestration.

---

License

MIT — see LICENSE for details.