pentester-mcp-security-tools

v2026.09.24
reason-machines/security-skills00

MCP server integrating 200+ penetration testing tools (nmap, sqlmap, ffuf, etc.) via Docker sandbox for AI-driven security testing

GitHub
Install command
npx skhub add reason-machines/pentester-mcp-security-tools
Markdown
SKILL.md

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.

Discovery
Tags

No tags published for this skill.

Version
Latest version metadata

Version

v2026.09.24

Published

Sep 24, 2026

Category

Uncategorized

License

NOASSERTION

Source path

skills/pentester-mcp-security-tools

Default branch

main

Latest commit

304c245

Tree SHA

010f47d