MCP Network Testing Server

A comprehensive, secure MCP (Model Context Protocol) server for remote network testing with built-in authentication, validation, and anti-jailbreaking guardrails.

⚠️ AI-Assisted Development Notice: Portions of this project were created with the assistance of AI tools, with human-in-the-loop (HITL) oversight and human-based testing. Despite these measures, AI-generated outputs can contain mistakes. Users are strongly encouraged to review, validate, and test the software for their own use cases. This project is provided "AS IS," without warranties of any kind.

Motivation

This MCP server was designed to bridge a critical gap when working with AI Agents (Claude Code, Codex, Gemini, Warp, OpenCode, etc.) for server configuration tasks. While these agents excel at generating configuration scripts for SMTP servers, web servers, VPNs with complex routing, and similar infrastructure tasks, they traditionally lacked the ability to validate whether their configurations actually work.

For example, an agent might generate a firewall rule to open a specific port or configure an SSL certificate, but it couldn't verify if the port is actually accessible or if the certificate is properly installed and trusted. By deploying this lightweight MCP server on a minimal cloud instance, agents can now perform real-world network validation tests, enabling them to iterate and self-correct their configurations based on actual results rather than assumptions.

� Quick Start

Get up and running in under 3 minutes:

Step 1: Install

# Install globally (recommended)
npm install -g @gtrevize/mcp-network

# OR clone from source
git clone https://github.com/gtrevize/mcp-network.git
cd mcp-network
npm install
npm run build

Step 2: First-Time Setup

Run the interactive setup to configure your environment:

# Global install:
mcp-network-setup

# Source install:
npm run build
bash scripts/setup.sh

This will:

Generate secure authentication credentials
Create your admin AUTH_TOKEN
Configure environment file (~/.mcp-network.env for global install, .env for source)
Provide startup instructions

Step 3: Start the Server

# Global install - load environment then start server
export $(cat ~/.mcp-network.env | xargs)
mcp-network-both  # Starts both MCP and REST API servers

# OR start only what you need:
# mcp-network-server  # MCP server only
# mcp-network-api     # REST API server only

# Source install:
npm run start:both  # Starts both servers
# npm start          # MCP server only
# npm run api        # REST API server only

The server is now running! You'll see:

MCP Server: Ready on stdio transport for MCP clients
REST API Server: Running on http://localhost:3001 (with Swagger docs at /api-docs)

Step 4: Use the Client

Test your setup with the interactive CLI client:

# Global install:
mcp-network-cli

# Source install:
npm run client

That's it! You now have a fully functional network testing environment. Perfect for:

Testing server configurations with AI agents
Learning the available network tools
Validating connectivity before deploying to production
Experimenting with network diagnostics

Production Deployment

For production environments, you'll want to run the server as a daemon:

See docs/DAEMON.md for comprehensive guides on:

PM2 process manager (recommended, cross-platform)
systemd (Linux)
launchd (macOS)
Docker (all platforms)

For cloud deployment to AWS, DigitalOcean, etc., see the Deployment section.

� Local vs Cloud Deployment

Choose the right deployment approach for your needs:

Aspect	Local CLI Client	Cloud Deployment
Setup Time	< 2 minutes	10-30 minutes
Cost	Free	$0-5/month (free tiers)
Use Case	Development, testing, learning	Production AI agent integration
Internet Required	For external targets only	Yes, for all operations
Security Risk	Minimal (local only)	Moderate (public exposure)
AI Agent Integration	Manual/scripting	Full MCP protocol support
Tool Limitations	Some tools need local admin	Full functionality
Scalability	Single user	Multiple concurrent agents
Persistence	Session-based	Always available
Network Testing	External targets only	Internal + external targets

When to Use Local CLI Client:

✅ Learning and experimenting with network tools
✅ Developing and testing configurations locally
✅ One-time network diagnostics and troubleshooting
✅ Validating configurations before cloud deployment
✅ Cost-sensitive scenarios or proof-of-concept work

When to Use Cloud Deployment:

✅ Production AI agent workflows
✅ Automated server configuration and validation
✅ Testing internal network infrastructure
✅ Multiple team members or agents need access
✅ Integration with CI/CD pipelines
✅ 24/7 availability requirements

�📚 Documentation

Comprehensive documentation is available in the docs/ directory:

QUICKSTART.md - Get started in 5 minutes
DEPLOYMENT.md - Production deployment guide
DAEMON.md - Running as a daemon (PM2, systemd, launchd, Docker)
API_README.md - REST API reference and examples
AUTH_README.md - Authentication & authorization
CONFIG_README.md - Configuration reference
SETUP.md - Detailed setup instructions
RELEASE.md - Release workflow and versioning
CHANGELOG.md - Version history and changes
CLAUDE.md - Architecture & development guide

Features

🌐 Multiple Access Methods

MCP Protocol: Native integration with Claude Desktop and MCP-compatible clients
REST API: Complete HTTP/HTTPS API with Swagger documentation
Interactive CLI: Rich terminal interface for local testing and development

🔒 Security First

JWT Authentication & RBAC: Single-token authentication with embedded user identity and roles
Input Validation: Comprehensive validation to prevent injection attacks
Anti-Jailbreaking: Pattern detection and sanitization to prevent malicious input
Access Logging: Complete audit trail of all tool executions
Timeout Management: Configurable timeouts with sensible defaults

🛠️ Network Testing Tools (14 Total)

DNS Lookup - Resolve DNS records (A, AAAA, MX, TXT, etc.)
IP Address Detection - Get server's public IPv4 address via DNS/API
IP Geolocation - Get geolocation info for IP addresses (country, city, ISP, coordinates)
iPerf3 - Network bandwidth testing (client/server mode)
Let's Encrypt - Certificate management with DNS/HTTP challenges
Ping - Test connectivity and measure latency (IPv4/IPv6)
Port Scanner - Throttled nmap scanning (single IP only)
Reverse DNS - PTR record lookup to find hostnames from IP addresses
Tcpdump - Packet capture with compression
API Testing - Postman-style HTTP/HTTPS endpoint testing
Port Testing - Check if specific ports are open
TLS/SSL Testing - Certificate validation and analysis
Traceroute - Trace network paths to destinations
WHOIS - Domain and IP address lookups

Installation

Prerequisites

Node.js >= 18.0.0
System tools: ping, traceroute, dig, whois, nmap, tcpdump, iperf3

Install Dependencies

npm install

Build

npm run build

Configuration

Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Required variables:

AUTH_TOKEN - Authentication token with user identity and roles (see "Generating Authentication Tokens" below)

Advanced variables (handled automatically by mcp-network-setup):

JWT_SECRET - Internal secret for token signing (auto-generated)

Optional variables:

LOG_LEVEL - Logging level (default: info)
NODE_ENV - Environment (development/production)
ACCESS_LOG_FILE - Path to access log file
LETSENCRYPT_PRODUCTION - Use production Let's Encrypt (default: false)

Generating Authentication Tokens

The server uses JWT tokens with embedded user identity and roles. Generate a token:

# Global install:
mcp-network-generate-token <userId> <role>
# Example: mcp-network-generate-token admin admin

# Source install:
npm run build
npm run config generate-token
# Or directly: npm run generate-token <userId> <role>

Set the generated token in your environment:

export AUTH_TOKEN="your-generated-token"

Role-Based Access Control

Available roles:

admin - Full access to all tools
network_engineer - Access to most network testing tools
developer - Access to basic network and API testing tools
auditor - Read-only network analysis tools
readonly - Minimal read-only access

Permissions

Each tool requires specific permissions:

network:api_test - API testing
network:dns - DNS resolution
network:ip_address - IP detection
network:ip_geolocation - IP geolocation
network:iperf - Bandwidth testing
network:letsencrypt - Certificate management
network:ping - Ping tool
network:port_scan - Port scanning (nmap)
network:port_test - Port testing
network:reverse_dns - Reverse DNS (PTR records)
network:tcpdump - Packet capture
network:tls_test - TLS/SSL testing
network:traceroute - Traceroute tool
network:whois - WHOIS lookups

Usage

Running the Servers

The project provides three server modes with two installation methods:

Option 1: Standalone Commands (Global Install)

After installing globally with npm install -g @gtrevize/mcp-network:

MCP Server Only (for Claude Desktop and MCP clients):

mcp-network-server

REST API Server Only (for HTTP/HTTPS access):

mcp-network-api

Both Servers Simultaneously (recommended for full access):

mcp-network-both

Option 2: npm Scripts (Source Install)

When running from source directory:

MCP Server Only:

# Production
npm start

# Development with auto-reload
npm run dev

REST API Server Only:

# Production
npm run api

# Development with auto-reload
npm run dev:api

Both Servers Simultaneously:

# Production - runs both MCP and REST API servers
npm run start:both

# Development - runs both with auto-reload
npm run dev:both

Note: The dual-server mode runs both servers in parallel:

MCP Server: stdio transport for MCP protocol clients
REST API Server: http://localhost:3001 (or configured API_PORT)

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

Prerequisites: Run mcp-network-setup first to generate your ~/.mcp-network.env file with AUTH_TOKEN.

Option 1: Global Install (Recommended)

{
  "mcpServers": {
    "network": {
      "command": "sh",
      "args": ["-c", "export $(cat ~/.mcp-network.env | xargs) && mcp-network-server"]
    }
  }
}

Option 2: Manual Configuration (Advanced)

If you prefer not to load from .env file:

{
  "mcpServers": {
    "network": {
      "command": "mcp-network-server",
      "env": {
        "AUTH_TOKEN": "your-auth-token-from-setup",
        "JWT_SECRET": "your-secret-from-env-file"
      }
    }
  }
}

Note: Both values are generated by mcp-network-setup and stored in ~/.mcp-network.env.

Option 3: Source Install

{
  "mcpServers": {
    "network": {
      "command": "sh",
      "args": ["-c", "export $(cat /path/to/mcp-network/.env | xargs) && node /path/to/mcp-network/dist/index.js"]
    }
  }
}

Example Tool Calls

Ping

{
  "name": "ping",
  "arguments": {
    "target": "example.com",
    "count": 4
  }
}

Port Scanner

{
  "name": "port_scan",
  "arguments": {
    "target": "192.168.1.1",
    "ports": "1-1000",
    "throttleMs": 100
  }
}

API Testing

{
  "name": "test_api",
  "arguments": {
    "url": "https://api.example.com/health",
    "method": "GET",
    "expectedStatus": 200
  }
}

TLS Certificate Check

{
  "name": "test_tls",
  "arguments": {
    "target": "example.com",
    "port": 443
  }
}

Interactive CLI Client

For local testing and development, the project includes a comprehensive interactive command-line client that eliminates the need for cloud deployment during development and testing phases.

Features

🎨 Rich Terminal UI: Colorized output with formatted tables and structured data
🔐 Built-in Authentication: Single JWT token with user identity and roles
📋 Interactive Tool Selection: Menu-driven interface for all 14 network tools
✅ Parameter Validation: Guided input with validation and confirmation
📊 Formatted Results: Clean, structured output with execution timing
⚡ Real-time Feedback: Progress indicators and status updates

Quick Start

# Development mode (recommended for testing)
npm run dev:client

# Or build and run
npm run build
npm run client

Authentication

The client supports multiple authentication methods:

# Method 1: Environment variable (recommended)
export AUTH_TOKEN="your-jwt-token"
npm run dev:client

# Method 2: Interactive prompt (client will ask for token)
npm run dev:client

Generate Authentication Token

# Global install:
mcp-network-generate-token <userId> <role>
# Example: mcp-network-generate-token cli-user admin

# Source install:
npm run build
npm run config generate-token
# Or directly: npm run generate-token <userId> <role>

Example Interactive Session

╔═══════════════════════════════════════════╗
║     MCP Network Testing Client            ║
║     Interactive Command Line Interface    ║
╚═══════════════════════════════════════════╝

✓ Connected to MCP server (14 tools available)

📋 Available Tools

1. ping - Send ICMP echo requests to test host reachability
2. traceroute - Trace the network path to a destination  
3. dns_lookup - Query DNS records for a domain
4. whois - Get domain registration information
5. ip_geolocation - Get geolocation data for IP addresses
...

? Select a tool to execute: ping

📝 Parameters for ping
? * target (Hostname or IP address): example.com  
? * count (Number of packets, 1-10): 4

📋 Execution Summary:
Tool: ping
Parameters: { target: "example.com", count: 4 }

? Execute this tool? Yes

⏳ Executing ping...
✓ ping completed (1.2s)

╔════════════════╗
║   ✓ SUCCESS    ║  
╚════════════════╝

Results:
host: example.com
packetsTransmitted: 4
packetsReceived: 4  
packetLoss: 0%
avgRtt: 25.3ms

? Execute another tool? No

Benefits for Local Development

No Cloud Deployment Required: Test all functionality locally during development
Rapid Iteration: Instant feedback without deployment cycles
Safe Testing: Experiment with tools without exposing services publicly
Development Workflow: Perfect for debugging and feature development
Cost-Effective: No cloud instance needed for initial testing and validation

Client Architecture

The CLI client consists of modular components:

Interactive Interface (index.ts): Main orchestration and user flow
MCP Connection (connection.ts): Server communication and tool execution
Parameter Prompts (prompts.ts): User input collection and validation
Result Formatter (formatter.ts): Colorized output and data presentation

This design allows for both interactive use and potential automation/scripting integration.

🌐 REST API Server

In addition to the MCP protocol and interactive CLI, the server provides a complete REST API for accessing all 14 network testing tools via HTTP/HTTPS. This makes it easy to integrate with web applications, automation scripts, and AI agents that don't support MCP natively.

Features

🔒 JWT Authentication: Same authentication system as MCP server
📖 Interactive Documentation: Swagger UI for API exploration and testing
🛡️ Security: Helmet.js, CORS, compression, and rate limiting
🎯 Complete Coverage: All 14 tools exposed via REST endpoints
📊 Structured Responses: Consistent JSON response format
⚡ Health Check: Unauthenticated endpoint for monitoring

Quick Start

# Option 1: Run API server only
npm run dev:api

# Option 2: Run both MCP and REST API servers (recommended)
npm run dev:both

# Access interactive documentation
open http://localhost:3001/api-docs

# Test an endpoint
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/tools

Note: Using npm run dev:both runs both the MCP server (stdio) and REST API server (HTTP) simultaneously, which is ideal for full-stack development and testing.

Configuration

Configure the REST API server via environment variables in .env:

API_PORT=3001                      # REST API server port (default: 3000)
API_ENABLED=true                   # Enable/disable API server
API_RATE_LIMIT_MAX=100             # Max requests per window
API_RATE_LIMIT_WINDOW_MS=60000     # Rate limit window (1 minute)

Example API Calls

Ping a host:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"google.com","count":4}' \
  http://localhost:3001/api/tools/ping

DNS lookup:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com","recordType":"A"}' \
  http://localhost:3001/api/tools/dns_lookup

Port scan:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"192.168.1.1","ports":"22,80,443"}' \
  http://localhost:3001/api/tools/port_scan

API Documentation

For complete API documentation including all endpoints, request/response formats, error handling, and production deployment guide, see docs/API_README.md.

When to Use REST API

Ideal for:

Web application integration
Automation scripts (Python, JavaScript, etc.)
AI agents without MCP support
Webhook integrations
CI/CD pipelines
Monitoring and alerting systems

Use MCP protocol instead for:

Claude Desktop integration
Native MCP client applications
Real-time bidirectional communication
Lower overhead communication

💡 Real-World Use Cases

AI Agent Server Configuration Scenarios

Scenario 1: NGINX with SSL Setup

Agent Task: "Configure NGINX with Let's Encrypt SSL for example.com"

AI Agent Workflow with MCP Network Server:
1. Agent generates NGINX configuration
2. Uses `letsencrypt` tool to obtain SSL certificate
3. Uses `tls_test` tool to verify certificate installation
4. Uses `port_test` tool to confirm ports 80/443 are accessible  
5. Uses `dns_lookup` tool to verify domain points to server
6. Agent iterates configuration based on test results

Scenario 2: VPN Server Validation

Agent Task: "Set up WireGuard VPN with proper routing"

AI Agent Workflow:
1. Agent configures WireGuard server and routing tables
2. Uses `ip_address` tool to get server's public IP
3. Uses `port_test` tool to verify VPN port accessibility
4. Uses `ping` tool to test connectivity through VPN tunnel
5. Uses `traceroute` tool to verify routing paths
6. Agent adjusts firewall rules based on connectivity tests

Scenario 3: Mail Server Configuration

Agent Task: "Configure Postfix SMTP server with proper DNS records"

AI Agent Workflow:
1. Agent sets up Postfix configuration
2. Uses `dns_lookup` tool to verify MX records
3. Uses `reverse_dns` tool to check PTR records
4. Uses `port_test` tool to verify SMTP ports (25, 587, 465)
5. Uses `tls_test` tool to validate SMTP TLS configuration
6. Agent fine-tunes configuration based on DNS and connectivity results

Scenario 4: Load Balancer Health Checks

Agent Task: "Configure HAProxy with health monitoring"

AI Agent Workflow:
1. Agent generates HAProxy configuration with backend servers
2. Uses `ping` tool to verify backend server connectivity
3. Uses `port_test` tool to check backend service ports
4. Uses `test_api` tool to validate HTTP health check endpoints
5. Uses `tls_test` tool for HTTPS backend verification
6. Agent adjusts backend weights and health check intervals

Benefits Over Traditional Approaches

Without MCP Network Server:

Agent generates configuration → Human manually tests → Human reports back to agent → Agent adjusts
Multiple manual intervention cycles
Prone to human error in testing
Slow iteration cycles

With MCP Network Server:

Agent generates configuration → Agent tests automatically → Agent self-corrects → Repeats until success
Fully automated validation loop
Consistent, repeatable testing
Rapid iteration and convergence

Performance & Limitations

Resource Usage

Memory: < 100MB typical usage, < 200MB peak during intensive operations
CPU: Minimal baseline usage, spikes during tool execution (1-5 seconds typical)
Network: Depends on tools used; packet capture and bandwidth testing use more resources
Concurrent Executions: Single-threaded tool execution to prevent resource conflicts

Tool-Specific Limitations

Port Scanner: Limited to single IP addresses (no subnet scanning)
Tcpdump: Requires elevated privileges on most systems
iPerf3: Server mode requires available port and firewall configuration
Let's Encrypt: Subject to ACME API rate limits (5 duplicate certificates per week)
DNS Tools: Limited by upstream DNS server response times and availability

Recommended Limits

Maximum execution time: 60 seconds per tool (configurable)
Concurrent clients: Single client connection (MCP protocol limitation)
File sizes: Tcpdump captures limited to 100MB by default
Request rate: No built-in rate limiting beyond tool-specific throttling

Scaling Considerations

For high-volume usage consider:

Deploy multiple instances behind a load balancer
Implement external rate limiting (nginx, cloudflare)
Use dedicated instances for bandwidth-intensive tools (iperf3, tcpdump)
Monitor disk space for packet captures and logs

Security Considerations

Input Validation

All inputs are validated against:

Shell injection patterns
Path traversal attempts
Malicious command sequences
Null bytes and control characters
Maximum length constraints

Rate Limiting

Tool-Level Rate Limiting:

Port scanner: Throttled with minimum delay
API testing: Configurable timeouts
Let's Encrypt: Subject to ACME rate limits

REST API Rate Limiting:

IP-based rate limiting (default: 100 requests per minute)
Configurable via API_RATE_LIMIT_MAX and API_RATE_LIMIT_WINDOW_MS
Applied to all /api/* endpoints
Health check endpoint exempt from rate limiting

Sandboxing

Some tools (like tcpdump and nmap) may require elevated privileges. Consider:

Running in Docker with appropriate capabilities
Using sudoers for specific commands only
Implementing network namespaces for isolation

Access Logging

All tool executions are logged with:

Timestamp
User ID
Tool name
Parameters
Success/failure status
Execution duration
Error messages

Important Caveat

SMTP Testing Limitation: While not related to the MCP server functionality itself, it's important to note that most cloud providers block outbound connections on port 25/tcp by default to prevent spam and abuse. This limitation will affect SMTP server testing and email delivery validation.

While resolving this limitation is beyond the scope of this documentation, solutions exist including:

Requesting port 25 unblocking from your cloud provider (available with most major providers)
Choosing cloud providers that don't impose this restriction by default
Using alternative SMTP ports (587, 465) for testing when applicable

Consult your cloud provider's documentation for their specific policies and procedures regarding SMTP traffic.

Deployment

This server (both MCP and REST API) has minimal system requirements, making it ideal for deployment on always-on, always-free cloud instances. The lightweight Node.js application typically uses less than 100MB of RAM and minimal CPU resources during operation.

Deployment Options:

MCP Server Only - For Claude Desktop and MCP clients (stdio transport)
REST API Only - For web applications and HTTP clients (port 3001)
Both Servers - Run simultaneously for maximum flexibility (npm run start:both)

Disclaimer: Cloud provider offerings and free tier specifications listed below are accurate as of November 2025 and are subject to change without notice. This information is provided for reference only. Always verify current pricing, availability, and terms directly with your chosen cloud provider.

Suitable Free Tier Options:

Oracle Cloud Always Free:

ARM Ampere A1 Compute (4 OCPUs, 24GB RAM) - Generous specs, perfect for this use case
VM.Standard.E2.1.Micro (1 OCPU, 1GB RAM) - More than sufficient for the MCP server

AWS Free Tier:

t2.micro (1 vCPU, 1GB RAM) - 750 hours/month for 12 months
t3.micro (2 vCPUs, 1GB RAM) - Better performance option

Google Cloud Free Tier:

e2-micro (2 vCPUs, 1GB RAM) - Always free in select regions
f1-micro (1 vCPU, 0.6GB RAM) - Minimal but functional

Azure Free Tier:

B1S (1 vCPU, 1GB RAM) - 750 hours/month for 12 months

Even the smallest instances provide more than enough resources to run the MCP server alongside basic system services. The server's efficient design ensures reliable operation without consuming significant system resources.

Security

⚠️ Important Security Considerations

While this MCP server implements decent security measures including JWT authentication, input validation, and anti-jailbreaking protections, deploying it on any publicly exposed system (cloud providers, VPS, etc.) introduces inherent security risks.

Security Scanning

This project uses Semgrep for automated security vulnerability scanning:

npm run semgrep

Scan Results: ✅ 0 vulnerabilities found (245 rules, 45 files scanned)

Note on TLS Verification: The tls-test tool intentionally uses rejectUnauthorized: false to inspect TLS certificates regardless of validity. This is expected behavior for a diagnostic tool (similar to openssl s_client, curl -k, or nmap ssl-enum-ciphers). The connection is only used to retrieve certificate metadata and is immediately closed - no sensitive data is transmitted. This has been documented and suppressed in semgrep with proper justification.

Strongly Recommended Security Measures:

Network-Level Protection:

Configure cloud provider security groups/firewalls to restrict access to essential ports only
- MCP Server: stdio transport (no port exposure needed)
- REST API Server: Port 3001 (or configured API_PORT)
Implement IP whitelisting using CIDR blocks to limit access to known networks
Consider VPN-only access for maximum security
Use HTTPS reverse proxy (nginx/Apache) for REST API in production

Instance-Level Security:

Enable and configure local firewall (iptables, ufw, Windows Firewall)
Regularly update the operating system and all dependencies
Use non-root users for running the service
Implement fail2ban or similar intrusion detection systems

Access Control:

Use the auto-generated secure credentials from mcp-network-setup
If tokens are compromised, regenerate them by running mcp-network-setup again (invalidates all existing tokens)
Monitor access logs for suspicious activity (includes userId from token)
Consider implementing additional rate limiting at the network level

Best Practice: Deploy the MCP server in a private subnet with access only through a bastion host or VPN connection, rather than exposing it directly to the internet.

Development

Project Structure

src/
├── index.ts              # Main MCP server entry point
├── types/                # TypeScript type definitions
├── auth/                 # JWT authentication and RBAC
├── middleware/           # Validation and guardrails
├── tools/                # Individual tool implementations (14 tools)
├── utils/                # Helper functions
├── logger/               # Logging system
├── client/               # Interactive CLI client
│   ├── index.ts          # CLI entry point
│   ├── connection.ts     # MCP connection management
│   ├── prompts.ts        # Interactive prompts
│   └── formatter.ts      # Result formatting
├── rest-api/             # REST API server
│   ├── server.ts         # Express server entry point
│   ├── middleware/       # Auth and error handling
│   ├── routes/           # API routes (health, tools)
│   └── swagger.ts        # OpenAPI specification
├── config/               # Configuration CLI
└── __tests__/            # Test suites (MCP + REST API)

Running Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Linting

npm run lint
npm run lint:fix

System Requirements

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y \
  iputils-ping \
  traceroute \
  dnsutils \
  whois \
  nmap \
  tcpdump \
  iperf3

RHEL/CentOS

sudo yum install -y \
  iputils \
  traceroute \
  bind-utils \
  whois \
  nmap \
  tcpdump \
  iperf3

macOS

brew install \
  nmap \
  tcpdump \
  iperf3 \
  whois

Troubleshooting

Permission Denied Errors

Some tools (nmap SYN scan, tcpdump) require root privileges:

# Run with sudo
sudo npm start

# Or use capabilities (Linux)
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/tcpdump

Authentication Errors

Ensure your JWT token is valid:

# Decode token to see its contents
node -e "const jwt = require('jsonwebtoken'); console.log(jwt.decode(process.env.AUTH_TOKEN));"

# Or regenerate token (global install)
mcp-network-generate-token <userId> <role>

# Or regenerate token (source install)
npm run config generate-token

Tool Not Found

Verify required system tools are installed:

which ping traceroute dig whois nmap tcpdump iperf3

npm Deprecation Warnings

During installation, you may see deprecation warnings for the following packages:

npm warn deprecated inflight@1.0.6
npm warn deprecated lodash.get@4.4.2
npm warn deprecated lodash.isequal@4.5.0
npm warn deprecated glob@7.1.6

These are safe to ignore. All deprecated packages are transitive dependencies (dependencies of dependencies) originating from swagger-jsdoc@6.2.8, which is used only for API documentation generation. They do not affect:

Production runtime behavior
Application security
Core functionality

Dependency Chain:

swagger-jsdoc@6.2.8 → glob@7.1.6 → inflight@1.0.6
swagger-jsdoc@6.2.8 → swagger-parser → z-schema → lodash.get, lodash.isequal

Future Resolution: We are monitoring swagger-jsdoc v7.0.0 (currently in release candidate) which addresses these deprecations. Once v7.0.0 is stable, we will upgrade to eliminate these warnings.

Contributing

This project follows security best practices. When contributing:

Validate all inputs
Implement proper error handling
Add comprehensive tests
Document security considerations
Follow the existing code style

License

MIT License - See LICENSE file for details

Support

For issues and questions:

GitHub Issues: https://github.com/robursoft/mcp-network/issues
Documentation: See docs/DEPLOYMENT.md for deployment guide

Roadmap

VPN testing (OpenVPN, WireGuard, IPSec)
WebSocket testing
SSH connectivity testing
Database connectivity testing
Cloud provider integration (AWS, Azure)
Enhanced Let's Encrypt automation
Web UI for management
Prometheus metrics export
Docker container with proper capabilities

Security Disclosure

If you discover a security vulnerability, please email security@robursoft.com instead of using the issue tracker.

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
docs		docs
scripts		scripts
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
config.json.sample		config.json.sample
env.sample		env.sample
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

gtrevize/mcp-network

Folders and files

Latest commit

History

Repository files navigation

MCP Network Testing Server

Motivation

� Quick Start

Step 1: Install

Step 2: First-Time Setup

Step 3: Start the Server

Step 4: Use the Client

Production Deployment

� Local vs Cloud Deployment

When to Use Local CLI Client:

When to Use Cloud Deployment:

�📚 Documentation

Features

🌐 Multiple Access Methods

🔒 Security First

🛠️ Network Testing Tools (14 Total)

Installation

Prerequisites

Install Dependencies

Build

Configuration

Environment Variables

Generating Authentication Tokens

Role-Based Access Control

Permissions

Usage

Running the Servers

Option 1: Standalone Commands (Global Install)

Option 2: npm Scripts (Source Install)

MCP Client Configuration

Example Tool Calls

Ping

Port Scanner

API Testing

TLS Certificate Check

Interactive CLI Client

Features

Quick Start

Authentication

Generate Authentication Token

Example Interactive Session

Benefits for Local Development

Client Architecture

🌐 REST API Server

Features

Quick Start

Configuration

Example API Calls

API Documentation

When to Use REST API

💡 Real-World Use Cases

AI Agent Server Configuration Scenarios

Benefits Over Traditional Approaches

Performance & Limitations

Resource Usage

Tool-Specific Limitations

Recommended Limits

Scaling Considerations

Security Considerations

Input Validation

Rate Limiting

Sandboxing

Access Logging

Important Caveat

Deployment

Suitable Free Tier Options:

Security

Security Scanning

Strongly Recommended Security Measures:

Development

Project Structure

Running Tests

Linting

System Requirements

Packages