pentester-mcp-security-tools

Pentester-MCP Security Tools

Skill by ara.so — Security Skills collection.

Pentester-MCP provides Model Context Protocol (MCP) integration for 200+ open-source penetration testing and cybersecurity tools. It enables AI assistants (Claude Desktop, Cursor, etc.) to autonomously execute security tools like nmap, sqlmap, ffuf, gobuster, nuclei, impacket, and hundreds more within a secure Docker sandbox.

Each tool is wrapped as an MCP server with AI-optimized documentation, safe argument handling, timeout enforcement, and output truncation to prevent shell injection and system pollution.

Installation

Docker Sandbox (Recommended)

The Docker approach isolates all 200+ tools in a container, avoiding host system pollution:

# Clone repository
git clone https://github.com/halilkirazkaya/pentester-mcp.git
cd pentester-mcp

# Configure desired tools in configs/example-config.yaml
# Set tools to true/false based on your needs

# Build and start container
docker compose up -d --build

# Verify container is running
docker ps | grep pentester-mcp

Local Execution (Advanced)

For Kali Linux, Parrot OS, or systems with tools pre-installed:

# Clone and setup
git clone https://github.com/halilkirazkaya/pentester-mcp.git
cd pentester-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Configuration

Tool Selection

Edit configs/example-config.yaml to enable/disable tools:

# Reconnaissance Tools
nmap: true
masscan: true
amass: true
subfinder: true
nuclei: true

# Web Exploitation
sqlmap: true
ffuf: true
gobuster: true
nikto: true
dirsearch: true

# Network & AD
impacket: true
responder: true
evil_winrm: true
bloodhound: false

# Password Tools
hydra: true
john: true
hashcat: false

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pentester_mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pentester-mcp",
        "/app/.venv/bin/python",
        "/app/server.py"
      ]
    }
  }
}

Cursor

Add to Cursor's MCP settings:

{
  "mcpServers": {
    "pentester_mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pentester-mcp",
        "/app/.venv/bin/python",
        "/app/server.py"
      ]
    }
  }
}

Local Execution Configuration

For host-based execution, modify the configuration:

{
  "mcpServers": {
    "pentester_mcp": {
      "command": "/path/to/pentester-mcp/.venv/bin/python",
      "args": ["/path/to/pentester-mcp/server.py"]
    }
  }
}

Tool Categories & Examples

Reconnaissance

Nmap - Network scanning and port enumeration:

# tools/nmap_mcp.py structure (auto-generated)
import subprocess
from typing import Optional

def run_nmap(
    target: str,
    flags: str = "-sV -sC",
    timeout: int = 300
) -> dict:
    """
    Execute nmap scan against target.
    
    Args:
        target: IP or hostname to scan
        flags: Nmap flags (e.g., -sV -sC -p-)
        timeout: Maximum execution time in seconds
    """
    cmd = ["nmap"] + flags.split() + [target]
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        timeout=timeout
    )
    return {
        "stdout": result.stdout[:8000],  # Truncated
        "stderr": result.stderr[:8000],
        "returncode": result.returncode
    }

Usage via AI:

• "Scan 192.168.1.1 with nmap using default scripts"
• "Run aggressive nmap scan on target.com"

Web Exploitation

SQLMap - Automated SQL injection testing:

# tools/sqlmap_mcp.py
def run_sqlmap(
    url: str,
    flags: str = "--batch --random-agent",
    timeout: int = 600
) -> dict:
    """
    Execute SQLMap against URL.
    
    Args:
        url: Target URL with parameter
        flags: SQLMap options
        timeout: Max execution time
    """
    cmd = ["sqlmap", "-u", url] + flags.split()
    # Safe execution without shell=True
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"output": result.stdout[:8000]}

FFUF - Web fuzzing:

# tools/ffuf_mcp.py
def run_ffuf(
    url: str,
    wordlist: str,
    flags: str = "-c -v",
    timeout: int = 300
) -> dict:
    """
    Execute ffuf directory/file fuzzer.
    
    Args:
        url: Target URL with FUZZ keyword
        wordlist: Path to wordlist file
        flags: Additional ffuf options
    """
    cmd = ["ffuf", "-u", url, "-w", wordlist] + flags.split()
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"output": result.stdout[:8000]}

Active Directory & Network

Impacket Suite - AD exploitation tools:

# tools/impacket_secretsdump_mcp.py
def run_secretsdump(
    target: str,
    username: str,
    password: Optional[str] = None,
    hashes: Optional[str] = None,
    timeout: int = 300
) -> dict:
    """
    Extract credentials from domain controller.
    
    Args:
        target: DC IP or hostname
        username: Domain username
        password: Password (or use hashes)
        hashes: LM:NTLM hash format
    """
    cmd = ["secretsdump.py"]
    if hashes:
        cmd.extend(["-hashes", hashes])
    cmd.append(f"{username}@{target}")
    # Execute with proper error handling
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"credentials": result.stdout[:8000]}

Password Cracking

Hydra - Brute force authentication:

# tools/hydra_mcp.py
def run_hydra(
    target: str,
    service: str,
    username: str,
    wordlist: str,
    flags: str = "-t 4",
    timeout: int = 600
) -> dict:
    """
    Brute force login credentials.
    
    Args:
        target: Target IP/hostname
        service: Service (ssh, ftp, http-post-form, etc.)
        username: Username to test
        wordlist: Password list path
        flags: Additional options
    """
    cmd = ["hydra", "-l", username, "-P", wordlist] + flags.split() + [target, service]
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"results": result.stdout[:8000]}

Common Patterns

AI-Driven Recon Workflow

When an AI assistant has Pentester-MCP configured, it can autonomously chain tools:

1. Initial Scan: "Scan example.com for open ports"

   • AI executes: nmap -sV -sC example.com

2. Web Discovery: AI detects port 80/443 open

   • Auto-executes: ffuf -u https://example.com/FUZZ -w /wordlists/common.txt

3. Vulnerability Testing: AI finds /admin directory

   • Auto-executes: sqlmap -u https://example.com/admin?id=1 --batch

Environment Variables for Credentials

Never hardcode secrets. Use environment variables:

# Set credentials in container
docker exec pentester-mcp sh -c 'export TARGET_USER=$TARGET_USER'

# Reference in AI queries
# "Use credentials from $TARGET_USER and $TARGET_PASS environment variables"

Custom Tool Configurations

Create custom config files for specific engagements:

# configs/web-pentest.yaml
nmap: true
ffuf: true
gobuster: true
sqlmap: true
nikto: true
nuclei: true
# Disable AD tools
impacket: false
bloodhound: false
responder: false

Update docker-compose.yml to use custom config:

services:
  pentester-mcp:
    volumes:
      - ./configs/web-pentest.yaml:/app/config.yaml

Unified Server Architecture

Instead of registering 235 individual MCP servers, Pentester-MCP uses a single unified server (server.py) that dynamically loads enabled tools:

# server.py (simplified structure)
from fastmcp import FastMCP
import importlib
import yaml

mcp = FastMCP("Pentester MCP")

# Load configuration
with open("config.yaml") as f:
    config = yaml.safe_load(f)

# Dynamically register enabled tools
for tool_name, enabled in config.items():
    if enabled:
        module = importlib.import_module(f"tools.{tool_name}_mcp")
        mcp.tool(module.run_tool)

# Start server
if __name__ == "__main__":
    mcp.run()

Troubleshooting

Container Not Running

# Check container status
docker ps -a | grep pentester-mcp

# View logs
docker logs pentester-mcp

# Restart container
docker compose down
docker compose up -d --build

Tool Not Found Errors

If AI reports tool not found:

1. Verify tool is enabled in configs/example-config.yaml
2. Rebuild container: docker compose up -d --build
3. Check tool binary exists in container: docker exec pentester-mcp which nmap

Timeout Issues

For long-running scans, increase timeout in tool invocation:

# Most tools accept timeout parameter
run_nmap(target="10.0.0.0/24", flags="-p-", timeout=1800)  # 30 minutes

Output Truncation

All tools truncate output to 8000 characters to prevent context overflow. For full output:

# Execute directly in container for full output
docker exec -it pentester-mcp nmap -p- target.com > full_output.txt

Permission Denied (Local Execution)

When running locally, some tools require root:

# Run with sudo
sudo /path/to/.venv/bin/python server.py

# Or add user to sudoers for specific tools
echo "$USER ALL=(ALL) NOPASSWD: /usr/bin/nmap" | sudo tee /etc/sudoers.d/pentester

Legal & Ethical Use

CRITICAL: Only use these tools on systems you own or have explicit written authorization to test. Unauthorized penetration testing is illegal. This project is for:

• Authorized security assessments
• Bug bounty programs with scope
• Educational lab environments
• Your own infrastructure testing

Always obtain proper authorization before running any security tools.