Network Scanner MCP

Network discovery and port scanning for infrastructure mapping.

Part of the Agentic System - a 24/7 autonomous AI framework with persistent memory.

Environmental awareness for the AGI cluster through network device discovery, port scanning, and service detection.

   ╭──────────────────────────────────────╮
   │  PIXEL'S NETWORK AWARENESS           │
   │                                      │
   │  "I can see everything on the        │
   │   network now - all devices,         │
   │   services, and cluster health!"     │
   ╰──────────────────────────────────────╯

Features

Device Discovery

• ARP Network Scanning: Discover all devices on the local network
• MAC Vendor Lookup: Identify device manufacturers
• Hostname Resolution: Resolve device hostnames via reverse DNS
• Device History: Track when devices first/last appeared
• Anomaly Detection: Alert when unknown devices join

Port Scanning & Service Detection

• Port Scanning: Scan specific ports or common service ports
• Service Fingerprinting: Identify services by port and banner
• Quick Scan Mode: Fast scan of common ports (22, 80, 443, etc.)
• Full Port Scan: Comprehensive scan of ports 1-1024
• Banner Grabbing: Capture service banners for identification

Cluster Monitoring

• Cluster Node Status: Monitor AGI cluster node connectivity
• Health Checks: Ping-based reachability testing with latency
• Alert Daemon: Continuous monitoring with voice and cluster alerts
• Node Recovery Detection: Alerts when nodes come back online

Alerting

• Voice Alerts: TTS alerts via edge-tts
• Node-Chat Integration: Broadcast alerts to cluster nodes
• Alert History: Persistent alert log with history

Installation

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

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

Alert Daemon Environment Variables

Cluster Nodes Configuration

Create 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"
  }
}

Or set via environment variable:

export CLUSTER_NODES_JSON='{"192.0.2.146": {"name": "orchestrator", "role": "orchestrator"}}'

MCP Tools

Device Discovery

Device Information

Network Topology

Port Scanning

Cluster Monitoring

Utilities

Usage Examples

Basic Network Discovery

# Scan the network
scan_network()

# Scan with hostname resolution
scan_network(resolve_names=True)

# Check for new devices
detect_new_devices()

# Find unknown devices
get_unknown_devices()

Device Management

# Mark your phone as known
mark_device_known(
    mac="00:00:00:00:00:63",
    label="Marc's iPhone",
    device_type="trusted"
)

# Get device details
get_device_info("192.0.2.217")
get_device_info("00:00:00:00:00:63")

# View device history
get_device_history()

Port Scanning

# Quick port scan (common ports)
scan_device_ports("192.0.2.217", quick=True)

# Scan specific ports
scan_device_ports("192.0.2.217", ports="22,80,443,8080")

# Full port scan (1-1024)
scan_device_ports("192.0.2.217", ports="all")

# Discover services on all devices
discover_services()

Cluster Monitoring

# Check cluster node status
get_cluster_nodes()

# Full health check with latency
check_cluster_health()

Network Topology

# Get full network topology
topology = get_network_topology()

# Returns categorized lists:
# - cluster_nodes: Configured cluster nodes
# - known_devices: Devices marked as trusted
# - unknown_devices: Unidentified devices

Alert Daemon

The alert daemon provides continuous network monitoring with alerts.

Running the Daemon

# Run directly
python -m network_scanner_mcp.alert_daemon

# Or use the installed script
network-scanner-daemon

Systemd Service

Install as a systemd service:

sudo cp network-scanner-daemon.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable network-scanner-daemon
sudo systemctl start network-scanner-daemon

Check status:

sudo systemctl status network-scanner-daemon
journalctl -u network-scanner-daemon -f

Alert Types

Data Storage

All data is stored in the configured data directory (default: ${AGENTIC_SYSTEM_PATH:-/opt/agentic}/databases/network-scanner/):

Integration

Enhanced Memory MCP

Device discoveries can be stored in enhanced-memory for pattern analysis and learning.

Node-Chat MCP

Alerts are broadcast to cluster nodes via node-chat when enabled.

Security Scanner MCP

Use export_for_security_scan() to get IP lists for vulnerability scanning with security-scanner-mcp.

Development

Running Tests

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

# Run tests
pytest

# Run with coverage
pytest --cov=network_scanner_mcp --cov-report=html

# Run specific test file
pytest tests/test_utils.py -v

Code Structure

src/network_scanner_mcp/
├── __init__.py       # Package exports
├── server.py         # MCP server with tools
├── scanner.py        # Scanning functionality
├── alert_daemon.py   # Continuous monitoring daemon
└── utils.py          # Shared utilities

Requirements

• Python 3.10+
• Root/sudo access for ARP scanning
• Network interface access

System Dependencies

• arp-scan - Required for ARP scanning
• edge-tts - Optional for voice alerts
• mpv - Optional for audio playback

Changelog

v0.2.0

• Added port scanning and service detection
• Added hostname resolution
• Implemented proper node-chat integration
• Refactored with shared utilities module
• Added comprehensive type hints
• Added thread-safe device registry
• Removed unused dependencies
• Added unit tests
• Fixed data format inconsistencies
• Auto-detect network interface

v0.1.0

• Initial release
• ARP scanning
• Device history tracking
• Basic cluster monitoring
• Alert daemon

Part of the AGI Agentic System - Environmental Awareness Component

Part of the MCP Ecosystem

This server integrates with other MCP servers for comprehensive AGI capabilities:

See agentic-system-oss for the complete framework.