🔒 Professional Penetration Testing MCP Server
A Model Context Protocol (MCP) server providing enterprise-grade penetration testing capabilities through a secure Docker container running comprehensive Kali Linux tools. Designed for professional security assessments and authorized penetration testing engagements.
🎯 Overview
This professional MCP server integrates 40+ industry-standard penetration testing tools into Claude Desktop, enabling AI-assisted security assessments for authorized environments. All tools run in an isolated Docker container with proper input sanitization, security measures, and automated result management.
⚡ Professional Features
🛠️ Comprehensive Tool Arsenal
Network Reconnaissance & Scanning
| Tool | Purpose | Professional Features |
|---|---|---|
| nmap | Network Discovery & Port Scanning | 6+ scan types (stealth, version, aggressive, full, UDP, vuln scripts) |
| masscan | High-Speed Port Scanner | Large-scale network discovery with configurable scan rates |
| dnsenum | DNS Enumeration | Comprehensive subdomain, nameserver, and zone transfer testing |
| amass | OWASP Subdomain Enumeration | Passive and active reconnaissance modes |
| traceroute | Network Path Analysis | Routing and topology identification |
| whois | Domain Registration Lookup | WHOIS information gathering |
Web Application Testing
| Tool | Purpose | Professional Features |
|---|---|---|
| nikto | Web Vulnerability Scanner | OWASP Top 10, SSL/TLS support, comprehensive misconfiguration detection |
| sqlmap | SQL Injection Testing | Multi-DBMS support, authentication, customizable risk/level |
| wpscan | WordPress Security Scanner | Plugin, theme, user enumeration with vulnerability database |
| ffuf | Fast Web Fuzzer | Directory, file, parameter, vhost discovery with filtering |
| nuclei | CVE & Misconfiguration Scanner | Template-based vulnerability detection |
| wafw00f | WAF Detection | Web Application Firewall fingerprinting |
| whatweb | Technology Fingerprinting | CMS, framework, server detection with aggression levels |
| gobuster | Fast Enumeration | Directory, DNS, VHost discovery with custom wordlists |
| dirb | Web Content Brute-forcing | Multiple wordlist support |
Exploitation & Vulnerability Research
| Tool | Purpose | Professional Features |
|---|---|---|
| searchsploit | Exploit Database Search | Local ExploitDB search with exact matching |
| metasploit | Exploitation Framework | Module search and exploit identification |
Password Cracking & Authentication Testing
| Tool | Purpose | Professional Features |
|---|---|---|
| hydra | Network Login Brute-forcing | SSH, FTP, HTTP, RDP, SMB support with rate limiting |
| john | Password Hash Cracking | Multi-format hash support with custom wordlists |
| hashcat | GPU-Accelerated Cracking | Advanced attack modes (dictionary, combinator, mask, hybrid) |
| hashid | Hash Type Identification | Automatic hash format detection |
Post-Exploitation & Enumeration
| Tool | Purpose | Professional Features |
|---|---|---|
| enum4linux | SMB/Samba Enumeration | User, share, group, policy enumeration |
| smbmap | SMB Share Auditing | Permission auditing with authentication |
SSL/TLS Security Testing
| Tool | Purpose | Professional Features |
|---|---|---|
| sslscan | SSL/TLS Testing | Cipher suite and protocol analysis |
| testssl.sh | Advanced SSL Vulnerability Scanner | Heartbleed, POODLE, BEAST, CRIME detection |
Wireless Security Testing
| Tool | Purpose | Professional Features |
|---|---|---|
| aircrack-ng | Wireless Security Suite | WPA/WPA2 password cracking from capture files |
🔐 Enterprise Security Features
- 🐳 Isolated Container Environment - Complete isolation using Kali Linux
- 🛡️ Advanced Input Sanitization - Multi-layer command injection prevention
- 👤 Non-root Execution - Minimal privilege principle with capability-based security
- 🔍 Input Validation - IP/domain/port format verification with regex patterns
- ⏱️ Timeout Protection - Configurable timeouts for all operations
- 📝 Comprehensive Logging - Full audit trail with structured logging
- 💾 Automatic Result Storage - Timestamped results with organized file management
- 📊 Result Management - List, read, and organize scan outputs
🚀 Quick Start
Prerequisites
- Docker Desktop installed and running
- Claude Desktop application (latest version)
- Git for repository cloning
- Administrative privileges for Docker operations
Installation
-
Clone the repository
git clone https://github.com/yourusername/pentest-mcp-server.git cd pentest-mcp-server -
Build the professional Docker image
docker build -t pentest-mcp-pro .Note: Initial build may take 15-30 minutes due to comprehensive tool installation
-
Configure Claude Desktop
Edit your Claude Desktop config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add this configuration:
{ "mcpServers": { "pentest_professional": { "command": "docker", "args": [ "run", "--rm", "-i", "--cap-add=NET_RAW", "--cap-add=NET_ADMIN", "--cap-add=NET_BIND_SERVICE", "pentest-mcp-pro", "python3", "pentest_server.py" ] } } } - Windows:
-
Restart Claude Desktop
Completely quit and restart Claude Desktop to load the new professional server.
-
Verify Installation
In Claude Desktop, you should see the professional pentest server connected with 40+ tools available.
📖 Professional Usage Examples
Network Reconnaissance
"Perform a comprehensive nmap scan on 192.168.1.0/24 with version detection"
"Run a stealth SYN scan on 10.0.0.1 ports 1-1000"
"Execute aggressive nmap scan with OS detection on target.local"
"Use masscan to quickly scan 192.168.1.0/24 for common ports at rate 5000"
"Enumerate subdomains for example.com using amass in passive mode"
"Perform comprehensive DNS enumeration on target-domain.com"
Web Application Testing
"Scan https://webapp.local with nikto including SSL checks"
"Test https://target.com/login.php for SQL injection with sqlmap at level 3 risk 2"
"Enumerate WordPress plugins and themes on https://blog.example.com"
"Run nuclei CVE scans against https://application.local"
"Use ffuf to discover hidden directories on https://target.com with big wordlist"
"Detect WAF on https://protected-site.com using wafw00f"
"Identify web technologies on https://target.com with aggressive whatweb scan"
Exploitation & Vulnerability Research
"Search for Apache 2.4.49 vulnerabilities in searchsploit"
"Find Metasploit modules for MS17-010 EternalBlue"
"Search exploits for ProFTPD 1.3.5 with exact matching"
Password & Authentication Testing
"Use hydra to brute-force SSH on 192.168.1.10 with username admin"
"Crack NTLM hashes from hashes.txt using john with rockyou wordlist"
"Identify hash type for 5f4dcc3b5aa765d61d8327deb882cf99"
"Run hashcat on MD5 hashes in hash-file.txt with dictionary attack"
Post-Exploitation
"Enumerate SMB shares on 192.168.1.20 using enum4linux"
"Test SMB share access on 192.168.1.20 with username guest"
"Map SMB permissions on 10.0.0.5 with credentials user:password"
SSL/TLS Security
"Test SSL/TLS configuration on https://secure.example.com:443"
"Check for SSL vulnerabilities on mail.example.com using testssl.sh"
"Analyze cipher suites on https://api.example.com with sslscan"
Results Management
"List the last 20 scan results"
"Show me the contents of the most recent nmap scan"
"Read the nikto scan results from [filename]"
🔧 Professional Tool Reference
Network Reconnaissance
nmap_scan(target, scan_type, ports)
- target: IP address, domain, or CIDR range
- scan_type:
basic- TCP connect scan (default)stealth- SYN stealth scan with OS detectionversion- Service version detection with default scriptsaggressive- OS detection, version detection, script scanning, traceroutefull- All ports with comprehensive detectionudp- UDP port scanvuln- Vulnerability detection scripts
- ports: Port specification (e.g., "80,443,8080" or "1-1000")
masscan_scan(target, ports, rate)
- target: IP address or CIDR range
- ports: Port range (default: "1-65535")
- rate: Packets per second (default: "1000", recommend 10000 for fast scans)
dnsenum_scan(domain)
- domain: Target domain for comprehensive DNS enumeration
amass_enum(domain, mode)
- domain: Target domain
- mode:
passive(OSINT only) oractive(includes DNS queries)
Web Application Testing
sqlmap_scan(url, data, cookie, level, risk)
- url: Target URL with parameters
- data: POST data for testing
- cookie: Session cookies
- level: Detection level 1-5 (default: 1)
- risk: Test risk level 1-3 (default: 1)
wpscan_scan(url, enumerate)
- url: WordPress site URL
- enumerate: Options -
vp(vulnerable plugins),vt(vulnerable themes),u(users)
nuclei_scan(target, templates)
- target: Target URL or domain
- templates: Template category (cves, misconfigurations, vulnerabilities, etc.)
ffuf_scan(url, wordlist, mode)
- url: Target URL (include /FUZZ for directory mode)
- wordlist:
common,big, or custom path - mode:
dir(directory) orvhost(virtual host)
Password Cracking
hydra_bruteforce(target, service, username, password_list)
- target: Target IP or hostname
- service: ssh, ftp, http-post-form, rdp, smb, etc.
- username: Username to test
- password_list:
rockyouor custom wordlist
hashcat_crack(hash_file, hash_type, attack_mode)
- hash_file: Path to file containing hashes
- hash_type: Hash mode (0=MD5, 100=SHA1, 1000=NTLM, 3200=bcrypt, etc.)
- attack_mode: 0=Dictionary, 1=Combinator, 3=Mask, 6=Hybrid
Results Management
list_results(limit)
- limit: Number of recent results to display (default: 10)
read_result(filename)
- filename: Name of result file to read
🏗️ Professional Architecture
Claude Desktop → MCP Protocol → Docker Container → Kali Linux Tools
↓
Input Sanitization & Validation
↓
Secure Tool Execution (pentester user)
↓
Result Storage & Management
↓
Formatted Output & Error Handling
Security Layers
- Input Layer: Multi-character sanitization, regex validation
- Execution Layer: Non-shell subprocess execution, timeout protection
- Permission Layer: Capability-based security, non-root user
- Storage Layer: Isolated workspace with proper permissions
- Network Layer: Controlled network capabilities
🛡️ Security & Legal Considerations
✅ Authorized Use Only
CRITICAL: This tool is designed exclusively for:
- Authorized penetration testing engagements with written permission
- Professional security assessments in controlled environments
- Bug bounty programs within defined scope
- Cybersecurity education and training on owned systems
- Red team exercises with proper authorization
- Security research on authorized targets
❌ Strictly Prohibited Uses
- ❌ Unauthorized scanning of third-party systems
- ❌ Attacking systems without explicit written permission
- ❌ Using discovered vulnerabilities maliciously
- ❌ Violating computer fraud and abuse laws (CFAA, Computer Misuse Act, etc.)
- ❌ Scanning internet-facing systems without authorization
- ❌ Denial-of-service attacks
- ❌ Data exfiltration or system compromise
📋 Professional Best Practices
-
Pre-Engagement
- Obtain written authorization before testing
- Define scope and boundaries clearly
- Establish rules of engagement
- Document chain of custody
-
During Engagement
- Stay within defined scope
- Document all activities
- Maintain communication with stakeholders
- Report critical findings immediately
-
Post-Engagement
- Provide comprehensive reports
- Follow responsible disclosure practices
- Securely delete sensitive data
- Archive results per contractual obligations
🔒 Technical Security Implementation
Input Sanitization
# Multi-layer protection
- Shell metacharacter filtering: ; & | ` $ ( ) < > \ " '
- IP/domain regex validation
- Port range validation (1-65535)
- CIDR notation support
- URL format verification
Container Security
- Based on official Kali Linux
- Non-root user (pentester UID 1000)
- Capability-based permissions (CAP_NET_RAW, CAP_NET_ADMIN)
- No persistent storage mounting
- Regular security updates
- Minimal attack surface
Command Execution
- subprocess.run() with shell=False
- Explicit argument arrays
- Configurable timeout protection
- Comprehensive error handling
- Result capture and sanitization
🧪 Development & Testing
Local Testing
# Test MCP server directly
docker run --rm -i pentest-mcp-pro python3 pentest_server.py
# Interactive container for debugging
docker run --rm -it pentest-mcp-pro /bin/bash
# Test individual tools
docker run --rm pentest-mcp-pro nmap --version
docker run --rm pentest-mcp-pro masscan --version
docker run --rm pentest-mcp-pro sqlmap --version
# Check tool availability
docker run --rm pentest-mcp-pro python3 -c "import subprocess; [print(f'{t}: {subprocess.run([\"which\", t], capture_output=True).returncode == 0}') for t in ['nmap', 'masscan', 'sqlmap']]"
Performance Optimization
# Multi-stage builds for smaller image size
# Cached wordlists for faster scanning
# Parallel tool installation in Dockerfile
# Pre-decompressed rockyou.txt wordlist
# Optimized Python dependencies
Adding Custom Tools
-
Install in Dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \ new-security-tool \ && rm -rf /var/lib/apt/lists/* -
Add capability if needed
RUN setcap cap_net_raw+eip /usr/bin/new-tool || true -
Create wrapper function
@mcp.tool() async def new_tool_scan(target: str = "") -> str: """Single-line professional description.""" # Implement security pattern target = sanitize_input(target) if not validate_ip_or_domain(target): return "❌ Error: Invalid target format" # Execute and handle results -
Update documentation and tool checklist
📁 Project Structure
pentest-mcp-server/
├── Dockerfile # Professional container configuration
├── requirements.txt # Python dependencies
├── pentest_server.py # Main MCP server (1000+ lines)
├── README.md # Professional documentation (this file)
├── CLAUDE.md # Implementation guidelines
├── LICENSE # MIT License
└── results/ # Auto-generated scan results (in container)
├── nmap_*.txt
├── nikto_*.txt
├── sqlmap_*.txt
└── ...
📊 Tool Statistics
- 40+ Professional Tools installed and configured
- 9 Tool Categories covering full pentest lifecycle
- Network Reconnaissance: 6 tools
- Web Application Testing: 9 tools
- Exploitation: 2 frameworks
- Password Cracking: 4 tools
- Post-Exploitation: 2 tools
- SSL/TLS Testing: 2 tools
- Wireless: 1 suite
- Utilities: 5+ additional tools
- Result Management: Built-in
🤝 Contributing
Professional contributions welcome! Please follow:
- Fork the repository
- Create feature branch (
git checkout -b feature/advanced-tool) - Follow security guidelines for new tools
- Add comprehensive tests and documentation
- Update tool statistics and documentation
- Submit detailed pull request
Contribution Guidelines
- Maintain security-first approach
- Add comprehensive error handling
- Include usage examples
- Update professional documentation
- Follow Python best practices (PEP 8)
- Add type hints where applicable
📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
⚠️ Disclaimer
IMPORTANT LEGAL NOTICE
This software is intended for authorized security testing and educational purposes only. Users are solely responsible for ensuring their use complies with:
- All applicable local, state, federal, and international laws
- Computer Fraud and Abuse Act (CFAA) in the United States
- Computer Misuse Act in the United Kingdom
- Similar legislation in other jurisdictions
- Terms of Service and Acceptable Use Policies
- Contractual obligations and authorization agreements
Unauthorized use of this software to:
- Scan, probe, or attack systems without explicit written authorization
- Access systems or data without permission
- Disrupt services or operations
- Violate privacy or security measures
...is strictly prohibited and may result in civil and criminal penalties.
The authors and contributors:
- Provide this software "as-is" without warranty
- Are not responsible for misuse or damage
- Do not endorse or encourage unauthorized activities
- Recommend consultation with legal counsel before use
By using this software, you acknowledge and agree to these terms.
🆘 Support & Community
- Issues: GitHub Issues
- Documentation: Check CLAUDE.md for implementation details
- Security Issues: Use responsible disclosure practices
- Professional Support: Contact for enterprise consulting
🏆 Acknowledgments
Built with:
- Kali Linux - Offensive Security
- Model Context Protocol - Anthropic
- Docker - Containerization platform
- FastMCP - Python MCP framework
- All the amazing open-source security tool developers
🏷️ Keywords
penetration-testing cybersecurity mcp-server kali-linux docker nmap metasploit sqlmap professional-security ethical-hacking security-tools claude-desktop vulnerability-scanning network-security web-security password-cracking post-exploitation
⭐ Star this repository if you find it useful for professional security assessments!
🔒 Always get authorization before testing systems you don't own.