NOT for educational purposes: An MCP server for professional penetration testers including STDIO/HTTP/SSE support, nmap, go/dirbuster, nikto, JtR, hashcat, wordlist building, and more.
Pentest MCP is a TypeScript MCP server for authorized security assessments. It gives a human researcher or a tool-using assessment agent one scoped interface for discovery, validation, capture, credential checks, local audit, evidence retrieval, and report preparation. Each active tool call is tied to an engagement and a durable record. The server checks the declared targets and time window; the researcher verifies findings before publication.
engagementId.allowedToolNames list permits only selected calls. Active tools also pass the engagement target and time gate.recordId values and correlated scope decisions with listEngagementRecords and getEngagementRecord. Records persist across restarts. Import external research with recordResearchActivity; the import does not replace MCP tool use.getClientReport.The declared-target check is an operational guardrail, not a complete network boundary. DNS changes, redirects, Nmap scripts, Nuclei templates, and other third-party tool behavior can create secondary traffic. Review tool configuration and keep network controls aligned with the engagement's rules.
The assessment stage is a tool-using agent session. runAgentAssessment supports local Codex or Claude in a dedicated account profile, Codex in a pinned container, a loopback OpenAI-compatible server such as llama.cpp or Ollama, and OpenRouter. CLI workers receive a locked, single-engagement Pentest MCP server and discover the full catalog. Guarded API models receive only the exact plan allowlist intersected with the worker catalog. Every requested action still reaches the same worker-side plan, target, parent-status, and time checks before a handler starts. Optional hostileModelProtection adds duplicate-action, token-accounting, and finish-reason circuit breakers and defaults to false. An interrupted run with a durable start receipt and no terminal receipt blocks replay; reconcileAgentAssessment requires an operator to confirm that the prior process stopped, records reviewer and rationale, and revokes the prior worker scope when it is still available. The returned toolCounts, importedRecordIds, and importMapRecordId identify recorded actions and imported evidence. A run with no successful assessment-tool call fails.
draftAssessmentReport is a later, context-quarantined report-writing step; a draft alone does not show that Pentest MCP helped the assessment. OpenAI, Anthropic, OpenRouter, OpenAI-compatible, local Codex, local Claude, container Codex, and configured SSH profiles can draft from a bounded evidence packet without scanner tools. local-agent accepts self-hosted CLI profiles and loopback OpenAI-compatible profiles while rejecting hosted providers before context is sent. The guarded model guide gives llama.cpp and OpenRouter profiles, enforced stop conditions, audit fields, and hostile-model deployment boundaries. The container assessment guide gives CLI profile fields, real acceptance command, and isolation limits. The agentic workflow covers scope, evidence review, Daybreak/Glasswing access, and Faxbot planning.
Release acceptance uses scripts/run-real-acceptance.mjs. It has no default target or authorization and refuses to pass unless installed Nmap and ProjectDiscovery HTTPX create successful evidence records. With --profile, the managed agent must invoke both through Pentest MCP. With --report-profile, a separate report context must produce the saved draft. Test doubles remain in automated tests only and are never shipped as acceptance receipts.
Requires Node.js 22.19.0 or newer and the host binaries for the tools you intend to use. The Docker image includes the listed tools; native installations must provide them in PATH.
npm install -g pentest-mcp
pentest-mcp
Stdio is the default for local MCP clients. pentest-mcp inspector starts the bundled MCP Inspector against this server over stdio; Inspector flags can be forwarded, for example pentest-mcp inspector --help.
Set PENTEST_DATA_DIR to choose the local evidence directory. Otherwise the server uses $XDG_DATA_HOME/pentest-mcp when that variable is set, or ~/.pentest-mcp. Evidence and report files are stored with private directory and file permissions. Treat raw outputs, hashes, captured traffic, and reports as client-sensitive data; control access, retention, and backups accordingly.
Call createEngagement before scanning. Use dates, targets, and references from the actual signed authorization; the values below are illustrative.
{
"tool": "createEngagement",
"arguments": {
"engagementId": "client-2026-10",
"authorizationReference": "Signed SoW section 4, approved 2026-10-24",
"notBefore": "2026-10-25T09:00:00-06:00",
"expiresAt": "2026-10-26T18:00:00-06:00",
"allowedTargets": ["app.example.com", "192.0.2.0/28"],
"excludedTargets": ["192.0.2.7"],
"testingWindows": [
{
"start": "2026-10-25T09:00:00-06:00",
"end": "2026-10-25T17:00:00-06:00"
}
]
}
}
Allowed targets accept exact hosts, CIDRs, wildcard subdomains, and HTTP(S) URL prefixes. Exclusions take precedence. All timestamps need an explicit timezone. getEngagement and listEngagements inspect stored registrations. closeEngagement revokes later execution, aborts managed assessments running in the same server process, and causes a separate managed runner to stop when it observes the parent registry closure.
Use the same engagementId for active tools. The default non-root container supports a TCP connect scan; SYN and OS detection need additional privileges that are not granted by default.
{
"tool": "nmapScan",
"arguments": {
"engagementId": "client-2026-10",
"target": "app.example.com",
"scanTechnique": "Connect",
"serviceVersionDetection": true
}
}
A successful tool response includes a recordId for its stored evidence. Retrieve only the records you need:
{
"tool": "listEngagementRecords",
"arguments": {
"engagementId": "client-2026-10",
"limit": 50
}
}