pentester-mcp-security-tools

---
name: pentester-mcp-security-tools
description: MCP server integrating 200+ penetration testing tools (nmap, sqlmap, ffuf, etc.) via Docker sandbox for AI-driven security testing
triggers:
  - run a penetration test with AI
  - scan a target with nmap through MCP
  - use pentester MCP tools for security testing
  - execute sqlmap or ffuf via Model Context Protocol
  - set up AI-powered penetration testing environment
  - configure pentester-mcp in Claude or Cursor
  - integrate cybersecurity tools with AI assistant
  - automate security scans using MCP server
---

# Pentester-MCP Security Tools

> Skill by [ara.so](https://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:

```bash
# 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:

```bash
# 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:

```yaml
# 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`:

```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:

```json
{
  "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:

```json
{
  "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:

```python
# 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:

```python
# 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:

```python
# 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:

```python
# 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:

```python
# 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:

```bash
# 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:

```yaml
# 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:

```yaml
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:

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

```bash
# 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:

```python
# 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:

```bash
# 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:

```bash
# 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.