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

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

🔐 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

Enable OAuth in your .env:

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

Start with HTTP transport:

MCP_TRANSPORT=http npm start

Connect with OAuth token:

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:

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

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.

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

A Model Context Protocol server that integrates essential penetration testing tools (Nmap, Gobuster, Nikto, John the Ripper) into a unified natural language interface, allowing security professionals to execute and chain multiple tools through conversational commands.

Related MCP Servers

CyberMCP
ricauts
A
security
A
license
A
quality
A Model Context Protocol server designed for testing backend APIs for security vulnerabilities like authentication bypass, injection attacks, and data leakage.
Last updated -
14
11
MIT License
NPM Sentinel MCP
Nekzus
A
security
A
license
A
quality
A Model Context Protocol server that enables AI-powered analysis of NPM packages through multiple tools for security vulnerability scanning, dependency analysis, package comparison, and quality assessment.
Last updated -
19
129
7
TypeScript
MIT License
Pentest Tools MCP Server
ch1nhpd
-
security
F
license
-
quality
An MCP server that integrates various penetration testing tools, enabling security professionals to perform reconnaissance, vulnerability scanning, and API testing through natural language commands in compatible LLM clients like Claude Desktop.
Last updated -
4
MCP Vulnerability Checker Server
firetix
A
security
A
license
A
quality
A Model Context Protocol server providing security vulnerability intelligence tools including CVE lookup, EPSS scoring, CVSS calculation, exploit detection, and Python package vulnerability checking.
Last updated -
8
6
MIT License

View all related MCP servers