Skip to main content
Glama
marc-shade

Network Scanner MCP

by marc-shade
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Network Scanner MCP

MCP Python-3.10+ License Part of Agentic System

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.

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/marc-shade/network-scanner-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server