pentest-mcp

# Pentest MCP: Professional Penetration Testing Toolkit [](https://smithery.ai/server/@DMontgomery40/pentest-mcp) [](https://mseep.ai/app/fa558a10-f45c-4668-9bb6-15630dd51f27) **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 - **OAuth 2.1 Support**: Secure authentication for network transports - **One Server, Multiple Security Options**: Same tools, same interface, your choice of transport and auth ### 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 and Hashcat - including custom wordlist generation - **GPU-Accelerated Cracking** with Hashcat - support for WPA/WPA2, NTLM, bcrypt, and 300+ hash types ### 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 ```bash npm install -g pentest-mcp ``` ### Install via Smithery ```bash npx -y @smithery/cli install @DMontgomery40/pentest-mcp --client claude ``` ### Run with your preferred transport ```bash # 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: ```json { "servers": [{ "name": "pentest-mcp", "command": "pentest-mcp" }] } ``` ### HTTP Streaming - Network Mode Deploy anywhere, access from anywhere: ```bash # 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: ```json { "servers": [{ "name": "pentest-mcp", "url": "http://localhost:8000/mcp" }] } ``` ### SSE - Legacy Support For backward compatibility with older clients: ```bash MCP_TRANSPORT=sse MCP_SERVER_PORT=8001 pentest-mcp ``` ## 🐳 Docker Deployment ### Simple Docker Run ```bash # 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 ```bash # 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 ```bash npm install -g pentest-mcp ``` ### Local Development ```bash git clone https://github.com/dmontgomery40/pentest-mcp.git cd pentest-mcp npm install npm run build ``` ### Platform-Specific Tool Installation ```bash # 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 ``` ## 🔐 OAuth Authentication (NEW) ### Secure Your Network Deployments Pentest MCP now supports OAuth 2.1 authentication for HTTP/SSE transports, enabling: - **Enterprise SSO Integration**: Connect to Auth0, Okta, Azure AD, or any OAuth provider - **Token-Based Security**: No more shared secrets or API keys - **Scoped Access Control**: Define granular permissions for different users - **Dynamic Client Registration**: Automatic client setup with compatible providers ### Quick OAuth Setup 1. **Enable OAuth** in your `.env`: ```bash MCP_OAUTH_ENABLED=true MCP_OAUTH_PROVIDER_URL=https://your-domain.auth0.com/oauth2 MCP_OAUTH_CLIENT_ID=your_client_id MCP_OAUTH_CLIENT_SECRET=your_client_secret MCP_OAUTH_SCOPES=read,write,scan ``` 2. **Start with HTTP transport**: ```bash MCP_TRANSPORT=http npm start ``` 3. **Connect with OAuth token**: ```javascript const client = new McpClient(); await client.connect('http://localhost:8000/mcp', { headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' } }); ``` ### OAuth Providers Supported - **Auth0**: Full support with custom scopes - **Google OAuth**: Enterprise workspace integration - **GitHub**: Team-based access control - **Azure AD**: Microsoft enterprise SSO - **Any OAuth 2.1 Provider**: PKCE-compliant providers ### OAuth Endpoints When OAuth is enabled, the following endpoints are available: - `/.well-known/oauth-authorization-server` - Authorization server metadata - `/.well-known/oauth-protected-resource` - Protected resource metadata - `/oauth/authorize` - Authorization endpoint (if acting as auth server) - `/oauth/token` - Token endpoint (if acting as auth server) ## 🛡️ 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: ```bash which nmap john gobuster nikto ``` ### Permission Denied For SYN scans and OS detection: ```bash # Run with sudo locally sudo pentest-mcp # Or use Docker with --privileged docker run --privileged pentest-mcp:latest ``` ### Build Issues ```bash 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 - [Migration Guide](MIGRATION.md) - Upgrading to v0.5.0 - [Usage Examples](usage-examples.sh) - Detailed transport examples - [Changelog](CHANGELOG.md) - Version history ## 🤝 Contributing Pull requests welcome at the [GitHub repository](https://github.com/dmontgomery40/pentest-mcp). Built for professionals by professionals. ## 📄 License GPL-3.0-or-later - See LICENSE file for details.