Pentest MCP - Professional Penetration Testing Toolkit

NOT for educational purposes - An MCP server for professional penetration testers

A Model Context Protocol server that integrates essential penetration testing tools including STDIO/HTTP/SSE support, nmap, gobuster, nikto, John the Ripper, hashcat, wordlist building, and more.

🚀 Multiple Transport Support

One Server, Multiple Security Options - Same tools, same interface, your choice of transport and auth:

• STDIO Transport: Default mode for local MCP clients
• HTTP Transport: Network mode with streaming support
• SSE Transport: Legacy compatibility for older MCP clients
• OAuth 2.1 Support: Secure authentication for network transports

🛠️ Core Tools Integration

🔍 Network Reconnaissance with Nmap

Full port scanning, service detection, and OS fingerprinting capabilities

🌐 Web Directory Enumeration with Gobuster

Find hidden paths and files with comprehensive wordlist support

🛡️ Web Vulnerability Scanning with Nikto

Comprehensive security checks and vulnerability identification

🔐 Advanced Password Cracking

• John the Ripper: Traditional password cracking with custom wordlist generation
• Hashcat: GPU-accelerated cracking with support for WPA/WPA2, NTLM, bcrypt, and 300+ hash types

⚡ Key Features

✅ Multi-Transport Architecture: STDIO, HTTP, and SSE support
✅ Professional/Student Modes: Configurable operational modes
✅ GPU Acceleration: Hashcat integration for high-performance cracking
✅ Docker Support: Containerized deployment with privileged access
✅ Natural Language Interface: Execute complex pentesting workflows conversationally
✅ Automated Reporting: Generate client-ready findings and recommendations
✅ OAuth 2.1 Security: Enterprise-grade authentication for network modes

🐳 Installation & Deployment

Quick Install via Smithery (Recommended)

npx -y @smithery/cli install @DMontgomery40/pentest-mcp --client claude

NPM Installation

npm install -g pentest-mcp

Docker Deployment

# STDIO mode (for local MCP clients)
docker run -it --rm --privileged pentest-mcp:latest

# HTTP mode (for network access)
docker run -p 8000:8000 -e MCP_TRANSPORT=http --privileged pentest-mcp:latest

Docker Compose (Multi-Profile)

# Clone and build
git clone https://github.com/dmontgomery40/pentest-mcp.git
cd pentest-mcp
docker-compose build

# Run your preferred transport
docker-compose --profile stdio up    # Local mode
docker-compose --profile http up     # Network mode  
docker-compose --profile sse up      # Legacy mode

🔧 Configuration & Usage

Transport Modes

# Local subprocess mode (default)
pentest-mcp

# Network mode with HTTP streaming
MCP_TRANSPORT=http pentest-mcp

# Legacy SSE mode
MCP_TRANSPORT=sse pentest-mcp

MCP Configuration

{
  "servers": [
    {
      "name": "pentest-mcp",
      "command": "npx pentest-mcp -y"
    }
  ]
}

Environment Variables

• MCP_TRANSPORT: Choose transport (stdio, http, sse)
• OAUTH_CLIENT_ID: OAuth client identifier for secure auth
• OAUTH_CLIENT_SECRET: OAuth client secret for authentication

💼 Professional Usage Examples

Network Assessment Workflow

“Set mode to professional. Scan 192.168.1.0/24 with SYN scan and service detection.”

Multi-Target Web Assessment

“Scan 10.0.1.0/24 for web servers. For each web server found, enumerate directories with gobuster using common.txt. Run nikto against all discovered web servers.”

Advanced Password Attack

“Generate a wordlist for company ‘Acme Corp’ founded in 1995 by John Smith. Use hashcat to crack these WPA2 handshakes with GPU acceleration.”

Automated Reporting

“Create a client report summarizing the findings from today’s assessment of the target network.”

🏢 Enterprise Features

Multi-Mode Operation

• Professional Mode: Full feature access with advanced capabilities
• Student Mode: Limited functionality for training environments

Advanced Cracking Capabilities

• 300+ Hash Types: Support for virtually any hash algorithm
• GPU Acceleration: Leverage CUDA/OpenCL for high-performance attacks
• Custom Wordlists: Intelligent generation based on target intelligence

Secure Network Operation

• OAuth 2.1: Enterprise authentication standards
• HTTP Streaming: Real-time progress and results
• Privileged Containers: Secure isolation with necessary permissions

🔒 Security & Legal Notice

⚠️ AUTHORIZED USE ONLY: This toolkit is designed exclusively for professional penetration testers operating under valid authorization.

Operational Security

• Privileged Access Required: SYN scans and OS detection require root/admin privileges
• Isolated Environments: Run in controlled, authorized test environments
• Network Monitoring: Monitor scan intensity on sensitive networks
• Legal Compliance: Ensure all activities comply with applicable laws and agreements

🐛 Troubleshooting

Common Issues

• HTTP not accessible: Check firewall rules and port bindings
• SSE connection drops: Ensure keep-alive is enabled
• STDIO hangs: Verify MCP client supports stdio transport
• Path Issues: Ensure all tools are installed and in your PATH
• Permission Errors: Check write access to scan_logs and temp_wordlists

Build from Source

# Clone and build
rm -rf node_modules dist
npm install
npm run build

🚀 Production Status

Current Status: Production Ready and Actively Maintained
Professional Grade: Built for real-world security assessments
Community: Pull requests welcome at the GitHub repository

📋 System Requirements

• Platform: Linux (optimized), Windows, macOS
• Node.js: v16+ with ESM support
• Docker: For containerized deployment
• Required Tools: Nmap, Gobuster, Nikto, John the Ripper, Hashcat
• Permissions: Root/admin for privileged network operations
• GPU: CUDA/OpenCL compatible for Hashcat acceleration (optional)

🤝 Contributing

This tool is built for professionals by professionals. Contributions, feedback, and pull requests are welcome at the GitHub repository.

📄 License

Licensed under the MIT License. See LICENSE for details.