Pentest MCP

Professional penetration-testing MCP server with modern transport/auth support and expanded recon tooling.

What Changed in 0.9.0

• Upgraded MCP SDK to @modelcontextprotocol/sdk@^1.26.0
• Kept MCP Inspector at the latest release (@modelcontextprotocol/inspector@^0.20.0) with bundled launcher
• Streamable HTTP is now the primary network transport (MCP_TRANSPORT=http)
• SSE is still available only as a deprecated compatibility mode
• Added bearer-token auth with OIDC JWKS and introspection support
• Added first-class tools: subfinderEnum, httpxProbe, ffufScan, nucleiScan, trafficCapture, hydraBruteforce, privEscAudit, extractionSweep
• Added report-admin tools: listEngagementRecords, getEngagementRecord
• Added SoW capture flow for reports using MCP elicitation (scopeMode=ask) with safe template fallback
• Hardened command resolution so web probing uses httpx-toolkit (preferred) or validated ProjectDiscovery httpx, avoiding Python httpx CLI collisions
• Integrated bundled MCP Inspector launcher (pentest-mcp inspector)
• Runtime baseline is now Node.js 22.7.5+
• Added invocation metadata in new tool outputs when auth/session context is available

Included Tools

• nmapScan
• runJohnTheRipper
• runHashcat
• gobuster
• nikto
• subfinderEnum
• httpxProbe
• ffufScan
• nucleiScan
• trafficCapture
• hydraBruteforce
• privEscAudit
• extractionSweep
• generateWordlist
• listEngagementRecords
• getEngagementRecord
• createClientReport
• cancelScan

Quick Start

Install

npm install -g pentest-mcp

Run locally (stdio)

pentest-mcp

Launch bundled MCP Inspector (no separate install)

pentest-mcp inspector

You can forward Inspector flags directly:

pentest-mcp inspector --help

Run over network (Streamable HTTP)

MCP_TRANSPORT=http MCP_SERVER_HOST=0.0.0.0 MCP_SERVER_PORT=8000 pentest-mcp

Run legacy SSE mode (deprecated)

MCP_TRANSPORT=sse MCP_SERVER_PORT=8001 pentest-mcp

Transport Notes

• stdio: default for local MCP clients.
• http: modern network transport. Recommended.
• sse: compatibility only. Deprecated and will be removed in a future major release.

Inspector Integration

• pentest-mcp inspector launches the bundled @modelcontextprotocol/inspector CLI.
• It auto-targets this MCP server over stdio by spawning:
  • node <this-package-entrypoint> stdio
• You do not need to install Inspector separately.

Auth Configuration (Bearer + OIDC)

Set these env vars when using MCP_TRANSPORT=http (or sse if needed):

MCP_AUTH_ENABLED=true
MCP_AUTH_MODE=bearer
MCP_AUTH_SCOPES=read,write
MCP_AUTH_AUDIENCE=
MCP_OIDC_ISSUER=https://issuer.example.com
MCP_OIDC_JWKS_URL=https://issuer.example.com/.well-known/jwks.json
# optional alternative/backup validation mode:
MCP_OIDC_INTROSPECTION_URL=https://issuer.example.com/oauth/introspect
MCP_OAUTH_CLIENT_ID=...
MCP_OAUTH_CLIENT_SECRET=...

Legacy aliases are still accepted temporarily:

• MCP_OAUTH_ENABLED
• MCP_OAUTH_PROVIDER_URL
• MCP_OAUTH_SCOPES

Workflow + Reporting

createClientReport now supports SoW handling modes:

• scopeMode=ask: prompt user via MCP elicitation (recommended)
• scopeMode=provided: use scopeOfWork value directly
• scopeMode=template: use built-in generic authorized-testing template

If elicitation is declined/unavailable, the report automatically falls back to the template.

Recon + Exploitation Examples

Subdomain enumeration

{
  "tool": "subfinderEnum",
  "arguments": {
    "domain": "example.com",
    "recursive": true,
    "allSources": true
  }
}

Probe live hosts

{
  "tool": "httpxProbe",
  "arguments": {
    "targets": ["example.com", "api.example.com"],
    "includeTitle": true,
    "includeStatusCode": true
  }
}

Fuzz content paths

{
  "tool": "ffufScan",
  "arguments": {
    "targetUrl": "https://example.com/FUZZ",
    "wordlist": "/usr/share/seclists/Discovery/Web-Content/common.txt",
    "threads": 40
  }
}

Template scanning

{
  "tool": "nucleiScan",
  "arguments": {
    "targets": ["https://example.com"],
    "severities": ["medium", "high", "critical"]
  }
}

Traffic capture (sniffing)

{
  "tool": "trafficCapture",
  "arguments": {
    "networkInterface": "eth0",
    "packetCount": 200,
    "bpfFilter": "tcp port 80"
  }
}

Brute-force checks

{
  "tool": "hydraBruteforce",
  "arguments": {
    "target": "10.10.10.20",
    "service": "ssh",
    "usernameList": "/usr/share/seclists/Usernames/top-usernames-shortlist.txt",
    "passwordList": "/usr/share/seclists/Passwords/Common-Credentials/10k-most-common.txt"
  }
}

SQLi extraction sweep

{
  "tool": "extractionSweep",
  "arguments": {
    "targetUrl": "https://target.local/item.php?id=1",
    "risk": 2,
    "level": 3
  }
}

Docker

docker-compose --profile http up
docker-compose --profile stdio up
docker-compose --profile sse up

The Docker image installs:

• nmap, john, hashcat, gobuster, nikto, ffuf, hydra, sqlmap, tcpdump
• subfinder, httpx + httpx-toolkit alias, nuclei

Required Host Tools (non-Docker runs)

Ensure the binaries are in PATH:

which nmap john hashcat gobuster nikto subfinder httpx-toolkit ffuf nuclei hydra sqlmap tcpdump

If httpx-toolkit is not installed, a validated ProjectDiscovery httpx binary is accepted as fallback.

Security Notice

Authorized use only. Run against systems/networks where you have explicit written permission.