pentest-mcp-server

Pentest MCP Server

A Model Context Protocol (MCP) 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 installed and running
• Claude Desktop installed
• Docker MCP Toolkit extension enabled in Docker Desktop

---

Installation

1. Clone the repo

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

2. Build the Docker image

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:

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
2. Copy your token from wpscan.com/profile
3. Set it as a Docker secret:

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