Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dmontgomery40/pentest-mcp

NOT for educational purposes: An MCP server for professional penetration testers including nmap, go/dirbuster, nikto, JtR, wordlist building, and more.
https://github.com/dmontgomery40/pentest-mcp

cybersecurity dirbuster gobuster john-the-ripper jtr mcp mcp-server model-context-protocol nikto nmap pentesting pentesting-tools redteam

Last synced: 12 months ago
JSON representation

NOT for educational purposes: An MCP server for professional penetration testers including nmap, go/dirbuster, nikto, JtR, wordlist building, and more.

Awesome Lists containing this project

README 

          
# Pentest MCP: Professional Penetration Testing Toolkit



[![smithery badge](https://smithery.ai/badge/@DMontgomery40/pentest-mcp)](https://smithery.ai/server/@DMontgomery40/pentest-mcp)

[![Verified on MseeP](https://mseep.ai/badge.svg)](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

- **One Server, Three Ways to Connect**: Same tools, same interface, your choice of transport



### 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 - including custom wordlist generation



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

```



## 🛡️ 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.