Content
# 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.
