Network Tools MCP

A Model Context Protocol implementation providing network diagnostics and scanning tools.

Tools Provided

• nmap_scan: Network scanning with port and service detection
• dns_lookup: Basic DNS queries for various record types
• dns_enum: Comprehensive DNS enumeration including subdomains
• whois_info: Basic domain registration information
• traceroute: Path tracing to a target host
• port_check: Check if a specific port is open on a host
• ssl_scan: SSL/TLS configuration and vulnerability analysis
• network_scan: Scan IP ranges for active hosts
• ip_geolocation: Get geographical information for an IP address
• http_headers: Analyze security headers of a website
• my_public_ip: Check your own public IP address and get detailed information

📦 Installation

Installing Manually

Install using uv:

uv tool install https://github.com/dkruyt/mcp-nettools.git

For development:

# Clone and set up development environment
git clone https://github.com/dkruyt/mcp-nettools.git
cd mcp-nettools

# Create and activate virtual environment
uv venv
source .venv/bin/activate

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

🔌 MCP Integration

Add this configuration to your MCP client config file:

{
    "mcpServers": {
        "mcp-nettools": {
            "command": "uv",
            "args": [
                "tool",
                "run",
                "mcp-nettools"
            ]
        }
    }
}

For Development:

{
    "mcpServers": {
        "mcp-nettools": {
            "command": "uv",
            "args": [
                "--directory",
                "path/to/cloned/mcp-nettools",
                "run",
                "mcp-nettools"
            ]
        }
    }
}

Running the Server

Using stdio transport (default)

# Using uv
uv run mcp-nettools

# Using Python directly
python -m mcp_nettools.cli

Using SSE transport

# Using uv
uv run mcp-nettools --transport sse --port 8000

# Using Python directly
python -m mcp_nettools.cli --transport sse --port 8000

You should see output similar to:

INFO:     Started server process [28048]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

🔧 Usage Examples

Network Scanning

# Basic scan
result = await session.call_tool("nmap_scan", {"host": "example.com"})

# Port-specific scan
result = await session.call_tool("nmap_scan", {
    "host": "example.com",
    "ports": "80,443,8080"
})

# Scan with specific arguments
result = await session.call_tool("nmap_scan", {
    "host": "example.com",
    "arguments": "-sV -sS -T4"
})

DNS Queries

# Basic A record lookup
result = await session.call_tool("dns_lookup", {
    "domain": "example.com",
    "record_type": "A"
})

# MX record lookup
result = await session.call_tool("dns_lookup", {
    "domain": "example.com",
    "record_type": "MX"
})

# Comprehensive DNS enumeration
result = await session.call_tool("dns_enum", {
    "domain": "example.com",
    "record_types": ["A", "AAAA", "MX", "TXT", "NS"]
})

Security Analysis

# Check HTTP headers
result = await session.call_tool("http_headers", {
    "url": "https://example.com"
})

# SSL/TLS scan
result = await session.call_tool("ssl_scan", {
    "target": "example.com"
})

# Customized SSL scan
result = await session.call_tool("ssl_scan", {
    "target": "example.com",
    "port": 443,
    "check_vulnerabilities": True,
    "check_certificate": True
})

⚠️ Security Notes

• Ensure you have proper authorization to scan networks and hosts
• Some tools may require root/administrator privileges to function correctly
• The nmap_scan and network_scan tools require the nmap executable to be installed
• For production use, consider limiting the network capabilities

🛠️ Development

Running Tests

# Install development dependencies
pip install ".[dev]"

# Run tests
pytest

Building the Package

# Install build tools
pip install build

# Build the package
python -m build

❓ Troubleshooting

• Some network scanning features may be limited based on your network environment and permissions
• For geolocation features, ensure your system has internet access
• If you encounter "Permission denied" errors with nmap or other tools, make sure you're running with appropriate privileges
• SSL scanning can be slow; if you need only certificate information, set check_vulnerabilities=False in the options
• If you encounter import errors, make sure all dependencies are installed