# Pentest MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that wraps common web penetration testing tools inside a Docker container and exposes them as Claude tools — for **educational use in controlled lab environments only**.

---

## Tools Available

| Tool | Binary | Description |
|---|---|---|
| `nmap_scan` | nmap | Port scan, service/OS detection |
| `nikto_scan` | nikto | Web server misconfiguration & vulnerability scan |
| `sqlmap_scan` | sqlmap | SQL injection detection and exploitation |
| `dirb_scan` | dirb | Web directory/file brute-force |
| `wpscan_scan` | wpscan | WordPress vulnerability scanner |
| `searchsploit_query` | searchsploit | ExploitDB search for known CVEs/exploits |
| `whois_lookup` | whois | Domain/IP registration info |
| `dns_recon` | dig | DNS record enumeration |
| `nc_banner_grab` | netcat | Raw TCP banner grabbing |
| `list_tools` | built-in | Show all tools and usage |

---

## Architecture

```
Claude Desktop
      │
      ▼
docker/mcp-gateway  (reads registry.yaml + custom.yaml)
      │
      ▼
pentest-mcp-server  (Debian + Kali tools, non-root)
      │
      ▼
nmap / nikto / sqlmap / dirb / wpscan / searchsploit / whois / dig / nc
```

---

## Prerequisites

- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running
- [Claude Desktop](https://claude.ai/download) installed
- Docker MCP Toolkit extension enabled in Docker Desktop

---

## Installation

### 1. Clone the repo

```bash
git clone https://github.com/YOUR_USERNAME/pentest-mcp-server.git
cd pentest-mcp-server
```

### 2. Build the Docker image

```bash
docker build -t pentest-mcp-server .
```

> First build takes ~3-5 minutes — it pulls Debian slim and installs all Kali tools.

### 3. Set up the MCP catalog

**Windows (CMD):**
```cmd
mkdir %USERPROFILE%\.docker\mcp\catalogs
copy custom.yaml %USERPROFILE%\.docker\mcp\catalogs\custom.yaml
```

**macOS / Linux:**
```bash
mkdir -p ~/.docker/mcp/catalogs
cp custom.yaml ~/.docker/mcp/catalogs/custom.yaml
```

### 4. Update the MCP registry

Open `%USERPROFILE%\.docker\mcp\registry.yaml` (Windows) or `~/.docker/mcp/registry.yaml` (macOS/Linux) and add under the `registry:` key:

```yaml
registry:
  pentest:
    ref: ""
```

### 5. Configure Claude Desktop

Open your Claude Desktop config:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

Replace or update the `mcpServers` section:

**Windows:**
```json
{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "//var/run/docker.sock:/var/run/docker.sock",
        "-v", "C:\\Users\\YOUR_USERNAME\\.docker\\mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ],
      "env": {
        "LOCALAPPDATA": "C:\\Users\\YOUR_USERNAME\\AppData\\Local",
        "ProgramData": "C:\\ProgramData",
        "ProgramFiles": "C:\\Program Files"
      }
    }
  }
}
```

**macOS / Linux:**
```json
{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/home/YOUR_USERNAME/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}
```

> Replace `YOUR_USERNAME` with your actual system username.

### 6. Restart Claude Desktop

Fully quit and reopen Claude Desktop. Open a **new chat** and type `list_tools` — you should see all 10 pentest tools listed.

---

## Optional: WPScan API Token

WPScan works without a token but won't return vulnerability data for plugins/themes. To enable it:

1. Register free at [wpscan.com/register](https://wpscan.com/register)
2. Copy your token from [wpscan.com/profile](https://wpscan.com/profile)
3. Set it as a Docker secret:

```bash
docker mcp secret set WPSCAN_API_TOKEN="your_token_here"
```

---

## Usage Examples

Ask Claude in a new chat:

```
Scan 192.168.56.101 for open ports
Run a full service version scan on 192.168.56.101
Run Nikto on http://192.168.56.101
Check http://192.168.56.101/login.php?id=1 for SQL injection
Brute-force directories on http://192.168.56.101
Scan the WordPress site at http://192.168.56.101/wp and enumerate plugins
Search ExploitDB for Apache 2.4 exploits
Grab the banner on port 22 of 192.168.56.101
Do a DNS lookup for example.local
```

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `CMD_TIMEOUT` | 300 | Max seconds for most commands |
| `NMAP_TIMEOUT` | 120 | Max seconds for nmap specifically |
| `WPSCAN_API_TOKEN` | (empty) | WPScan API token for vuln data |

---

## Security Design

- **Non-root container** — runs as `mcpuser` (uid 1000)
- **Input allowlisting** — every parameter regex-validated before subprocess call
- **Flag whitelists** — only a curated set of flags accepted per tool
- **No `shell=True`** — all commands passed as lists to `subprocess.run()`
- **No secrets in logs** — tokens never logged

---

## Troubleshooting

**Tools not showing in Claude:**
```bash
# Confirm image exists
docker images | grep pentest

# Test gateway manually (Windows)
docker run --rm -i -v //var/run/docker.sock:/var/run/docker.sock -v %USERPROFILE%\.docker\mcp:/mcp docker/mcp-gateway --catalog=/mcp/catalogs/docker-mcp.yaml --catalog=/mcp/catalogs/custom.yaml --config=/mcp/config.yaml --registry=/mcp/registry.yaml --tools-config=/mcp/tools.yaml --transport=stdio
```

Look for `pentest: (10 tools)` in the output.

**`docker mcp gateway run` shows 0 tools:**
Use the explicit `docker run docker/mcp-gateway` style in `claude_desktop_config.json` instead — the shorthand doesn't mount the Docker socket correctly on Windows.

**nmap returns permission errors:**
The Dockerfile runs `setcap` on nmap. Rebuild: `docker build -t pentest-mcp-server .`

**Build fails with 404 apt errors:**
Kali's rolling mirrors occasionally lag. Wait 10 minutes and retry — it's a transient mirror sync issue.

---

## ⚠️ Legal Notice

This tool is for **authorized, educational use only**. Only scan systems you own or have **explicit written permission** to test. Unauthorized scanning is illegal in most jurisdictions.

---

## License

MIT