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

Variable	Default	Description
NETWORK_SCANNER_DATA_DIR	$AGENTIC_SYSTEM_PATH/databases/network-scanner	Data storage directory
NETWORK_INTERFACE	Auto-detected	Network interface to use
DEFAULT_SCAN_SUBNET	Auto-detected	Default subnet for scans
LOG_LEVEL	INFO	Logging level
LOG_TO_FILE	false	Enable file logging
CLUSTER_NODES_JSON	None	JSON string of cluster nodes

Alert Daemon Environment Variables

Variable	Default	Description
SCAN_INTERVAL_SECONDS	300	Seconds between scans
VOICE_ALERTS_ENABLED	true	Enable voice alerts
NODE_CHAT_ALERTS_ENABLED	true	Enable cluster alerts
ALERT_ON_NEW_DEVICES	true	Alert on new device detection
ALERT_ON_CLUSTER_NODE_DOWN	true	Alert when cluster nodes go offline
TTS_VOICE	en-IE-EmilyNeural	Voice for TTS alerts
MAX_ALERT_HISTORY	1000	Maximum alerts to retain

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

Tool	Description
scan_network(subnet?, resolve_names?)	ARP scan for all devices on subnet
detect_new_devices()	Find only new devices since last scan
get_unknown_devices()	List unidentified devices

Device Information

Tool	Description
get_device_info(identifier)	Details about device (by IP or MAC)
get_device_history(mac?)	Historical data for devices
mark_device_known(mac, label, device_type)	Label a device as trusted
remove_device_known(mac)	Remove device from known list

Network Topology

Tool	Description
get_network_topology()	Full topology with categorization

Port Scanning

Tool	Description
scan_device_ports(target, ports?, quick?)	Scan ports on specific device
discover_services()	Quick scan all devices for services

Cluster Monitoring

Tool	Description
get_cluster_nodes()	Status of configured cluster nodes
check_cluster_health()	Ping all nodes and report health

Utilities

Tool	Description
ping_device(target, count?)	Ping device for reachability
resolve_device_hostname(target)	Resolve hostname via DNS
get_scanner_status()	Get scanner status and configuration
export_for_security_scan()	Export IPs for security-scanner-mcp

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

Type	Trigger	Priority
new_device	Unknown device detected	High
node_offline	Cluster node unreachable	Critical
node_recovered	Cluster node back online	Normal

Data Storage

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

File	Description
device_history.json	All discovered devices with metadata
known_devices.json	Devices marked as known/trusted
cluster_nodes.json	Cluster node configuration
alert_history.json	Alert log (last 1000 alerts)
pending_alerts.json	Queued alerts for delivery
server.log	MCP server logs (if enabled)
alert_daemon.log	Alert daemon logs

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:

Server	Purpose
enhanced-memory-mcp	4-tier persistent memory with semantic search
agent-runtime-mcp	Persistent task queues and goal decomposition
agi-mcp	Full AGI orchestration with 21 tools
cluster-execution-mcp	Distributed task routing across nodes
node-chat-mcp	Inter-node AI communication
ember-mcp	Production-only policy enforcement

See agentic-system-oss for the complete framework.