How do I use mcp-nettools?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-nettools nmap scan of example.com" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

mcp-nettools