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

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

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