Submit

A comprehensive MCP (Model Context Protocol) server for penetration testing tools.

MCP Penetration Testing Server Setup Guide

This guide will walk you through setting up a comprehensive MCP (Model Context Protocol) server for penetration testing tools.

Prerequisites

System Requirements

  • Linux/macOS (recommended) or Windows with WSL2
  • Node.js 18+ and npm
  • Python 3.8+ (for some tools)
  • Git

Security Tools Installation

On Ubuntu/Debian:
# Update package list
sudo apt update

# Install basic tools
sudo apt install -y nmap gobuster nikto hydra john hashcat ffuf

# Install dirsearch
sudo apt install -y python3-pip
pip3 install dirsearch

# Install nuclei
sudo apt install -y golang-go
go install -v github.com/projectdiscovery/nuclei/v2/cmd/nuclei@latest
sudo ln -s ~/go/bin/nuclei /usr/local/bin/nuclei
On macOS:
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install tools
brew install nmap gobuster nikto hydra john hashcat ffuf
brew install nuclei

# Install dirsearch
pip3 install dirsearch
On Arch Linux:
# Install from official repositories
sudo pacman -S nmap gobuster nikto hydra john hashcat

# Install from AUR
yay -S ffuf nuclei dirsearch

Wordlists Setup

# Create wordlists directory
sudo mkdir -p /usr/share/wordlists

# Download common wordlists
sudo git clone https://github.com/danielmiessler/SecLists.git /usr/share/wordlists/seclists

# Download dirb wordlists
sudo apt install -y dirb  # This installs wordlists in /usr/share/wordlists/dirb/

# Or manually download
sudo wget -O /usr/share/wordlists/common.txt https://raw.githubusercontent.com/danielmiessler/SecLists/master/Discovery/Web-Content/common.txt

MCP Server Setup

Step 1: Create Project Directory

mkdir mcp-pentest-server
cd mcp-pentest-server

Step 2: Initialize Node.js Project

npm init -y

Step 3: Install Dependencies

# Install MCP SDK
npm install @modelcontextprotocol/sdk

# Install development dependencies
npm install -D nodemon

Step 4: Create Server Files

Save the provided JavaScript code as server.js and the package.json configuration.

Step 5: Make Server Executable

chmod +x server.js

Step 6: Test the Server

# Test if server starts correctly
node server.js

Claude Desktop Integration

Step 1: Locate Claude Desktop Config

The configuration file is located at:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/claude_desktop/claude_desktop_config.json

Step 2: Create/Update Configuration

Create or update the configuration file with the following content:

{
  "mcpServers": {
    "pentest-server": {
      "command": "node",
      "args": ["/full/path/to/your/mcp-pentest-server/server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Important: Replace /full/path/to/your/mcp-pentest-server/server.js with the actual absolute path to your server file.

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server configuration.

Usage Examples

Once configured, you can use the following commands in Claude Desktop:

Basic Port Scan

Please run an nmap scan on 192.168.1.1 using the quick scan type

Web Directory Enumeration

Run a gobuster scan on http://example.com with php,html,txt extensions

Vulnerability Scanning

Perform a nuclei scan on example.com focusing on CVE templates

Comprehensive Reconnaissance

Run a comprehensive scan on example.com including web and vulnerability scanning

Password Attacks

Use hydra to brute force SSH on 192.168.1.100 with username admin and password list /usr/share/wordlists/rockyou.txt

Configuration Options

Custom Wordlist Paths

You can specify custom wordlist paths in the tool parameters:

{
  "target": "http://example.com",
  "wordlist": "/custom/path/to/wordlist.txt"
}

Scan Optimization

For better performance, you can adjust:

  • Thread counts (typically 10-50 depending on target)
  • Timeout values in the server code
  • Scan intensity levels

Security Considerations

Network Segmentation
  • Only run scans on networks you own or have explicit permission to test
  • Use isolated testing environments when possible
Rate Limiting
  • Implement delays between requests to avoid overwhelming targets
  • Consider using proxy chains for anonymity
Logging
  • Enable detailed logging for compliance and debugging
  • Store scan results securely

Troubleshooting

Common Issues

Tool Not Found
# Check if tool is in PATH
which nmap
which gobuster

# Add to PATH if necessary
export PATH=$PATH:/usr/local/bin
Permission Errors
# Some tools require root privileges
sudo chmod +x server.js
sudo node server.js
Port Access Issues
# For privileged ports, run with sudo
sudo node server.js

Debug Mode

Enable debug logging by setting environment variable:

DEBUG=true node server.js

Log Files

Check system logs for detailed error information:

# On Linux
journalctl -u mcp-pentest-server

# Manual log file
tail -f /var/log/mcp-pentest.log

Advanced Configuration

Custom Tool Integration

To add new tools, extend the server class:

async runCustomTool(args) {
  const { target, options } = args;
  const command = `custom-tool ${target} ${options}`;
  
  try {
    const { stdout } = await execAsync(command);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          tool: 'custom-tool',
          target,
          results: this.parseCustomOutput(stdout)
        }, null, 2)
      }]
    };
  } catch (error) {
    throw new Error(`Custom tool failed: ${error.message}`);
  }
}

Database Integration

For result storage, consider integrating with databases:

const sqlite3 = require('sqlite3');
const db = new sqlite3.Database('pentest_results.db');

// Store scan results
async storeScanResult(result) {
  const query = `
    INSERT INTO scans (target, tool, timestamp, results)
    VALUES (?, ?, ?, ?)
  `;
  
  return new Promise((resolve, reject) => {
    db.run(query, [
      result.target,
      result.tool,
      result.timestamp,
      JSON.stringify(result.parsed_results)
    ], function(err) {
      if (err) reject(err);
      else resolve(this.lastID);
    });
  });
}

API Integration

For external API integration:

const axios = require('axios');

async queryThreatIntel(target) {
  try {
    const response = await axios.get(`https://api.threatintel.com/lookup/${target}`, {
      headers: { 'Authorization': `Bearer ${process.env.THREAT_INTEL_API_KEY}` }
    });
    return response.data;
  } catch (error) {
    console.error('Threat intel lookup failed:', error);
    return null;
  }
}

Security Best Practices

  1. Principle of Least Privilege: Run the server with minimal required permissions
  2. Input Validation: Sanitize all user inputs to prevent command injection
  3. Rate Limiting: Implement request throttling to prevent abuse
  4. Audit Logging: Log all scan activities for compliance
  5. Network Isolation: Use dedicated networks for testing
  6. Data Encryption: Encrypt sensitive scan results at rest
  7. Regular Updates: Keep all tools and dependencies updated

Legal Considerations

  • Only scan systems you own or have explicit written permission to test
  • Comply with local laws and regulations regarding security testing
  • Maintain proper documentation of authorized testing activities
  • Consider bug bounty program rules and scope limitations
  • Implement proper data handling and privacy protection measures

Support and Contributing

For issues, improvements, or questions:

  1. Check the troubleshooting section
  2. Review tool documentation
  3. Submit issues with detailed error logs
  4. Consider contributing improvements back to the project

License

This project is licensed under the MIT License - see the LICENSE file for details.

MCP Server · Populars

MCP Server · New