pentest-mcp

Pentest MCP: Professional Penetration Testing Toolkit

Multi-transport MCP server for penetration testing - works locally via stdio, over the network via HTTP streaming, or with legacy SSE clients. Run it in Docker, deploy it remotely, or use it locally - your choice.

🚀 Key Features

Multi-Transport Architecture

• STDIO Transport: Traditional subprocess communication for local MCP clients
• HTTP Streaming Transport: Modern network protocol with full bidirectional support
• SSE Transport: Legacy compatibility for older MCP clients
• One Server, Three Ways to Connect: Same tools, same interface, your choice of transport

Professional Pentesting Tools

• Network Reconnaissance with Nmap - full port scanning, service detection, OS fingerprinting
• Web Directory Enumeration with Gobuster - find hidden paths and files
• Web Vulnerability Scanning with Nikto - comprehensive security checks
• Password Cracking with John the Ripper - including custom wordlist generation

Intelligent Workflow Integration

• Natural language interface for complex commands
• Tool chaining for comprehensive assessments
• Context-aware suggestions for next steps
• Automated client-ready reporting
• Voice control compatible (with speech-to-text)

🎯 Quick Start

Install via npm

npm install -g pentest-mcp

Install via Smithery

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

Run with your preferred transport

# Local subprocess mode (default)
pentest-mcp

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

# Legacy SSE mode
MCP_TRANSPORT=sse pentest-mcp

📡 Transport Options

STDIO (Default) - Local Subprocess

Perfect for Claude Desktop and local development:

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

HTTP Streaming - Network Mode

Deploy anywhere, access from anywhere:

# Start server
MCP_TRANSPORT=http pentest-mcp

# Or with Docker
docker run -p 8000:8000 -e MCP_TRANSPORT=http --privileged pentest-mcp:latest

Configure your client:

{
  "servers": [{
    "name": "pentest-mcp",
    "url": "http://localhost:8000/mcp"
  }]
}

SSE - Legacy Support

For backward compatibility with older clients:

MCP_TRANSPORT=sse MCP_SERVER_PORT=8001 pentest-mcp

🐳 Docker Deployment

Simple Docker Run

# 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 with Profiles

# 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
docker-compose --profile http up
docker-compose --profile sse up

Environment Variables

• MCP_TRANSPORT: Choose transport (stdio, http, sse)
• MCP_SERVER_HOST: Bind address (default: 0.0.0.0)
• MCP_SERVER_PORT: Server port (default: 8000)

💬 Usage Examples

Network Discovery

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

Web Application 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.
Create a client report summarizing the findings.

Custom Password Attack

Generate a wordlist for company "Acme Corp" founded in 1995 by John Smith.
Crack these hashes using the generated wordlist:
admin:$1$xyz$...
user:$1$abc$...

🔧 System Requirements

• Tools Required: nmap, john, gobuster, nikto (must be in PATH)
• Node.js: v16+ for ESM support
• Permissions: Root/admin for SYN scans and OS detection
• Platform: Works on any OS, optimized for Kali Linux

📦 Installation Options

Global Install

npm install -g pentest-mcp

Local Development

git clone https://github.com/dmontgomery40/pentest-mcp.git
cd pentest-mcp
npm install
npm run build

Platform-Specific Tool Installation

# macOS
brew install nmap john-jumbo gobuster nikto

# Debian/Ubuntu
sudo apt update
sudo apt install nmap john gobuster nikto

# Kali Linux (pre-installed)
# All tools come pre-installed

🛡️ Security & Legal

⚠️ AUTHORIZED USE ONLY: This toolkit is for professional penetration testers operating under valid scope of work. Use only on systems and networks for which you have explicit written authorization.

🐳 Docker Security Note: The --privileged flag is required for certain scans (SYN, OS detection). Only use in trusted environments or VMs.

🔍 Troubleshooting

Tools Not Found

Ensure all required tools are in your PATH:

which nmap john gobuster nikto

Permission Denied

For SYN scans and OS detection:

# Run with sudo locally
sudo pentest-mcp

# Or use Docker with --privileged
docker run --privileged pentest-mcp:latest

Build Issues

rm -rf node_modules dist
npm install
npm run build

Transport-Specific 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

📚 Documentation

• - Upgrading to v0.5.0
• - Detailed transport examples
• - Version history

🤝 Contributing

Pull requests welcome at the GitHub repository. Built for professionals by professionals.

📄 License

GPL-3.0-or-later - See LICENSE file for details.