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
• 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

Install via Smithery

Run with your preferred transport

📡 Transport Options

STDIO (Default) - Local Subprocess

Perfect for Claude Desktop and local development:

HTTP Streaming - Network Mode

Deploy anywhere, access from anywhere:

Configure your client:

SSE - Legacy Support

For backward compatibility with older clients:

🐳 Docker Deployment

Simple Docker Run

Docker Compose with Profiles

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

Web Application Assessment

Custom Password Attack

🔧 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

Local Development

Platform-Specific Tool Installation

🔐 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:

2. Start with HTTP transport:

3. Connect with OAuth 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:

Permission Denied

For SYN scans and OS detection:

Build Issues

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 - Upgrading to v0.5.0
• Usage Examples - Detailed transport examples
• Changelog - 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.