FrenzyVJN/pentestfrenzymcp

Pentesting MCP Server

A comprehensive Model Context Protocol (MCP) server providing professional penetration testing tools and utilities. This server integrates seamlessly with Claude Desktop and other MCP-compatible clients, giving you access to industry-standard security testing tools directly in your AI conversations.

🛡️ Features

Network Security Tools

• Nmap Scanning: Comprehensive port scanning with various scan types (quick, full, stealth, UDP, version detection, OS detection)
• DNS Lookup: Query DNS records (A, AAAA, MX, NS, TXT, CNAME, SOA)
• WHOIS Lookup: Domain registration and ownership information

Web Application Security

• Nikto Scanning: Web vulnerability scanning for common security issues
• DIRB: Directory and file brute forcing with wordlists
• Gobuster: Fast directory, DNS, and virtual host brute forcing

Reconnaissance & OSINT

• Sublist3r: Subdomain enumeration using multiple search engines (Google, Bing, Yahoo, etc.)

🚀 Quick Start

Prerequisites

• Docker (recommended) or Python 3.10+
• Claude Desktop application

Step 1: Build the MCP Server

Option A: Docker (Recommended)

# Clone the repository
git clone https://github.com/FrenzyVJN/pentestfrenzymcp
cd pentestfrenzymcp

# Build the Docker image
./build.sh

# Test the installation
./simple-test.sh

Option B: Local Installation

# Install Python dependencies
pip install httpx mcp dnspython sublist3r

# Install system tools (macOS)
brew install nmap nikto dirb gobuster whois

# Install system tools (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install nmap nikto dirb gobuster whois dnsutils

Step 2: Configure Claude Desktop

For macOS

1. Open the Claude Desktop configuration file:

# Create the directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

# Edit the configuration file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Add the MCP server configuration:

Docker setup (recommended):

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "pentest-mcp:latest"
      ]
    }
  }
}

Local installation:

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "python3",
      "args": ["/full/path/to/pentest-mcp/main.py"],
      "cwd": "/full/path/to/pentest-mcp"
    }
  }
}

For Windows

1. Open the Claude Desktop configuration file:

# Navigate to the Claude config directory
cd %APPDATA%\Claude

# Create/edit the configuration file
notepad claude_desktop_config.json

2. Add the MCP server configuration:

Docker setup (recommended):

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "pentest-mcp:latest"
      ]
    }
  }
}

WSL (Windows Subsystem for Linux):

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "wsl",
      "args": [
        "-e",
        "docker",
        "run",
        "--rm",
        "-i",
        "--network=host",
        "pentest-mcp:latest"
      ]
    }
  }
}

Local Windows installation:

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "python",
      "args": ["C:\\full\\path\\to\\pentest-mcp\\main.py"],
      "cwd": "C:\\full\\path\\to\\pentest-mcp"
    }
  }
}

Step 3: Restart Claude Desktop

After updating the configuration file, completely restart Claude Desktop to load the new MCP server.

Step 4: Verify Connection

1. Open Claude Desktop
2. Start a new conversation
3. Look for the MCP server indicator (usually a small icon or status indicator)
4. Try a simple command: "Can you do a DNS lookup for google.com?"

💬 Usage Examples

Once configured, you can use these natural language commands in Claude Desktop:

🔍 Network Reconnaissance

"Can you scan the top 1000 ports on scanme.nmap.org?"
"Do a quick nmap scan on 127.0.0.1"
"Perform a stealth scan on 192.168.1.1"
"Scan ports 22,80,443 on example.com with version detection"

🌐 DNS & Domain Analysis

"Look up DNS A records for google.com"
"Get all MX records for github.com"
"Do a WHOIS lookup for microsoft.com"
"Find the nameservers for cloudflare.com"

🔎 Subdomain Discovery

"Find subdomains for example.com using sublist3r"
"Enumerate subdomains for target.com with bruteforce enabled"
"Discover subdomains for company.com using all search engines"

🛡️ Web Application Testing

"Run a nikto scan on http://testphp.vulnweb.com"
"Use dirb to find directories on http://example.com"
"Perform directory brute forcing on https://target.com using gobuster"
"Scan for common web vulnerabilities on https://demo.site.com"

🎯 Advanced Scanning Scenarios

"Do a comprehensive security assessment of 192.168.1.100"
"Perform reconnaissance on example.com including subdomains and port scan"
"Check if port 22 is open on a list of IP addresses: 10.0.0.1, 10.0.0.2"

🛠️ Available Tools

🔧 Advanced Configuration

Auto-approve Tools (Skip Confirmations)

Add tools to the autoApprove list to skip confirmation dialogs:

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--network=host", "pentest-mcp:latest"],
      "autoApprove": [
        "dns_lookup",
        "whois_lookup",
        "nmap_scan"
      ]
    }
  }
}

Custom Wordlists

Mount custom wordlists for directory brute forcing:

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "/path/to/wordlists:/wordlists:ro",
        "pentest-mcp:latest"
      ]
    }
  }
}

Environment Variables

Set custom environment variables:

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--network=host", "pentest-mcp:latest"],
      "env": {
        "SCAN_TIMEOUT": "30",
        "MAX_THREADS": "20"
      }
    }
  }
}

🔍 Troubleshooting

MCP Server Not Appearing

1. Check configuration file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Verify JSON syntax: Use a JSON validator to check your configuration

3. Restart Claude Desktop completely (not just refresh)

4. Check Docker: Ensure Docker is running and the image exists:

   docker images pentest-mcp
   

Tools Not Working

1. Test Docker container manually:

   docker run --rm -it pentest-mcp:latest bash
   

2. Check tool availability:

   ./simple-test.sh
   

3. Verify network access: Ensure --network=host is used for scanning external targets

Permission Issues

• macOS: Grant Docker access to network resources
• Windows: Run Docker Desktop as administrator if needed
• Linux: Add user to docker group: sudo usermod -aG docker $USER

⚠️ Security & Legal Considerations

🚨 Important Warnings

• Authorization Required: Only use these tools on systems you own or have explicit written permission to test
• Legal Compliance: Ensure compliance with local laws and regulations
• Responsible Disclosure: Follow responsible disclosure practices for any vulnerabilities found
• Rate Limiting: Be respectful with scan rates to avoid overwhelming target systems

🔒 Security Features

• Container Isolation: Tools run in isolated Docker containers
• No Persistent Storage: Containers are destroyed after each use
• Network Isolation: Optional network isolation for testing
• Audit Logging: All tool executions are logged

🏗️ Architecture

The server uses a modular architecture for easy extension:

pentest/
├── __init__.py          # Package initialization
├── tools.py             # Tool definitions and schemas
├── handlers.py          # Tool call routing and handling
├── network.py           # Network tools (nmap, DNS, WHOIS)
├── web.py              # Web security tools (nikto, dirb, gobuster)
└── recon.py            # Reconnaissance tools (sublist3r)

Adding New Tools

1. Define the tool in pentest/tools.py
2. Implement the handler in pentest/handlers.py
3. Create the tool class in the appropriate module
4. Update the tools list in get_all_tools()

See the existing tools for examples and patterns to follow.

🤝 Contributing

Contributions are welcome! Please:

1. Follow the existing code patterns
2. Add comprehensive error handling
3. Include security considerations
4. Test with both Docker and local installations
5. Update documentation

📄 License

This project is for educational and authorized security testing purposes only. Users are responsible for ensuring compliance with applicable laws and obtaining proper authorization before testing any systems.