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

mkdir %USERPROFILE%\.docker\mcp\catalogs
copy custom.yaml %USERPROFILE%\.docker\mcp\catalogs\custom.yaml

macOS / Linux:

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:

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

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

# 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