Network Scanner

You use the Network Scanner MCP to map your network, discover devices, scan ports and services, and monitor cluster health. It provides automated discovery, real-time alerts, and integration with other MCP servers to keep your network infrastructure visible and healthy.

How to use

You use an MCP client to run the Network Scanner MCP as part of your Agentic System. Start the server, configure your environment, and then invoke the available tools to perform device discovery, port scanning, and cluster monitoring. Typical workflows include discovering devices on a subnet, identifying unknown devices, scanning common ports to detect services, and checking the health of cluster nodes. Alerts can be enabled to notify you about new devices or cluster node status changes, and results are stored for historical analysis.

How to install

Prerequisites: Python 3.10+, a Python virtual environment, and appropriate system permissions for ARP scanning.

cd ${AGENTIC_SYSTEM_PATH:-/opt/agentic}/mcp-servers/network-scanner-mcp
source ${AGENTIC_SYSTEM_PATH:-/opt/agentic}/.venv/bin/activate

# Install the package
pip install -e .

# For development (includes tests)
pip install -e ".[dev]"

# Install system dependencies (Fedora)
sudo dnf install arp-scan

# For voice alerts (optional)
pip install edge-tts
sudo dnf install mpv

Configuration

The Network Scanner MCP uses a dedicated MCP server configuration and a set of environment variables to control data paths, interfaces, scan behavior, and cluster integration.

# MCP Server Configuration
# Add to ~/.claude.json
{
  "mcpServers": {
    "network-scanner": {
      "command": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}/.venv/bin/python",
      "args": ["-m", "network_scanner_mcp.server"],
      "cwd": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}/mcp-servers/network-scanner-mcp/src"
    }
  }
}

Environment variables

Configure runtime behavior with the following environment variables.

# Global scanner
NETWORK_SCANNER_DATA_DIR="${AGENTIC_SYSTEM_PATH:-/opt/agentic/databases/network-scanner}"
NETWORK_INTERFACE="Auto-detected"
DEFAULT_SCAN_SUBNET="Auto-detected"
LOG_LEVEL="INFO"
LOG_TO_FILE="false"
CLUSTER_NODES_JSON=None

# Alert daemon
SCAN_INTERVAL_SECONDS="300"
VOICE_ALERTS_ENABLED="true"
NODE_CHAT_ALERTS_ENABLED="true"
ALERT_ON_NEW_DEVICES="true"
ALERT_ON_CLUSTER_NODE_DOWN="true"
TTS_VOICE="en-IE-EmilyNeural"
MAX_ALERT_HISTORY="1000"

Cluster nodes configuration

Define the cluster nodes that participate in the monitoring and alerting workflow by creating cluster_nodes.json in the data directory.

{
  "192.0.2.146": {
    "name": "orchestrator",
    "role": "orchestrator",
    "type": "cluster_node"
  },
  "192.0.2.196": {
    "name": "builder",
    "role": "builder",
    "type": "cluster_node"
  },
  "192.0.2.233": {
    "name": "researcher",
    "role": "researcher",
    "type": "cluster_node"
  }
}

Alert daemon and system service

Run the alert daemon to enable continuous monitoring and voice/cluster alerts.

# Run directly
python -m network_scanner_mcp.alert_daemon

# Or use the installed script
network-scanner-daemon

Data storage

All data is stored in the configured data directory, including device history, known devices, cluster nodes, and alerts.

Available tools

scan_network

ARP scan for all devices on a subnet to build a device list.

detect_new_devices

Identify devices that have appeared since the last scan.

get_unknown_devices

Return devices that are not yet recognized as known.

get_device_info

Fetch detailed information about a device by IP or MAC.

get_device_history

Retrieve historical data for a device.

mark_device_known

Mark a device as trusted or known with a label and type.

remove_device_known

Remove a device from the known list.

get_network_topology

Return a full network topology with categorized groups.

scan_device_ports

Scan ports on a specific device with optional port filters.

discover_services

Perform a quick scan to identify services on devices.

get_cluster_nodes

Check status of configured cluster nodes.

check_cluster_health

Ping cluster nodes and report latency-based health.

ping_device

Ping a device to test reachability.

resolve_device_hostname

Resolve a device's hostname via DNS.

get_scanner_status

Return current status and configuration of the scanner.

export_for_security_scan

Export IPs for security-scanner-mcp.