NOT for educational use: An MCP server for Nmap and John the Ripper, for professional penetration testers. Supports stdio, HTTP, and SSE transports with OAuth 2.1 authentication.
npm install pentest-mcp

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.
bash
npm install -g pentest-mcp
`$3
`bash
npx -y @smithery/cli install @DMontgomery40/pentest-mcp --client claude
`$3
`bash
Local subprocess mode (default)
pentest-mcpNetwork mode with HTTP streaming
MCP_TRANSPORT=http pentest-mcpLegacy SSE mode
MCP_TRANSPORT=sse pentest-mcp
`📡 Transport Options
$3
Perfect for Claude Desktop and local development:
`json
{
"servers": [{
"name": "pentest-mcp",
"command": "pentest-mcp"
}]
}
`$3
Deploy anywhere, access from anywhere:
`bash
Start server
MCP_TRANSPORT=http pentest-mcpOr 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"
}]
}
`$3
For backward compatibility with older clients:
`bash
MCP_TRANSPORT=sse MCP_SERVER_PORT=8001 pentest-mcp
`🐳 Docker Deployment
$3
`bash
STDIO mode (for local MCP clients)
docker run -it --rm --privileged pentest-mcp:latestHTTP mode (for network access)
docker run -p 8000:8000 -e MCP_TRANSPORT=http --privileged pentest-mcp:latest
`$3
`bash
Clone and build
git clone https://github.com/dmontgomery40/pentest-mcp.git
cd pentest-mcp
docker-compose buildRun your preferred transport
docker-compose --profile stdio up
docker-compose --profile http up
docker-compose --profile sse up
`$3
- 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
$3
`
Set mode to professional.
Scan 192.168.1.0/24 with SYN scan and service detection.
`$3
`
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.
`$3
`
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
$3
`bash
npm install -g pentest-mcp
`$3
`bash
git clone https://github.com/dmontgomery40/pentest-mcp.git
cd pentest-mcp
npm install
npm run build
`$3
`bash
macOS
brew install nmap john-jumbo gobuster niktoDebian/Ubuntu
sudo apt update
sudo apt install nmap john gobuster niktoKali Linux (pre-installed)
All tools come pre-installed
`🔐 OAuth Authentication (NEW)
$3
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
$3
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'
}
});
`$3
- 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
$3
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
$3
Ensure all required tools are in your PATH:
`bash
which nmap john gobuster nikto
`$3
For SYN scans and OS detection:
`bash
Run with sudo locally
sudo pentest-mcpOr use Docker with --privileged
docker run --privileged pentest-mcp:latest
`$3
`bash
rm -rf node_modules dist
npm install
npm run build
``- Migration Guide - Upgrading to v0.5.0
- Usage Examples - Detailed transport examples
- Changelog - Version history
Pull requests welcome at the GitHub repository. Built for professionals by professionals.
GPL-3.0-or-later - See LICENSE file for details.