pentest-mcp

An authorization-gated penetration testing MCP server for agentic AI — 80 tools that install into any MCP-capable agent: Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Roo Code, Zed, OpenCode, Continue, and anything else that speaks the Model Context Protocol.

Every network-touching tool refuses to run without an engagement file that records the client's written authorization and the exact in-scope targets. The gate lives in code, not in a prompt, so no conversation can talk the plugin into testing something it is not allowed to test.

Capabilities

Highlights

• pentest_assess_web(url, deep=True) — one call runs the whole web battery: headers, fingerprinting, crawl, sensitive paths, TLS, CORS, secrets, then reflection and hidden-parameter discovery.
• pentest_attack_surface(domain) — maps the external attack surface: DNS, WHOIS, certificate transparency (crt.sh), Wayback Machine, subdomain takeover, cloud storage buckets. Active steps only run when the engagement allows them.
• CVE intelligence — pentest_vuln_cve_lookup pulls published CVEs from NVD based on the product/version fingerprints.
• JWT & secret hunting — offline JWT analysis (alg=none, embedded jwk, missing claims, common HMAC secret cracking) and leaked-credential detection in JS/responses with values always redacted.
• Layered exploitation — Metasploit check mode first, msfvenom payloads into the evidence directory only, hydra capped at 50 users / 50 passwords.
• Dashboard-ready output — SARIF 2.1.0 (GitHub code scanning, DefectDojo), standalone HTML, CVSS v3.x calculator, and a wave-based remediation plan.
• Tooling integrations — import Burp (XML) and ZAP (JSON) reports into standardized findings, drive the ZAP API from the agent, controlled passthrough to the Burp REST API, and one-call export to DefectDojo (with dry_run).
• CTF toolkit — encodings (auto-detect), XOR brute-force, Caesar/frequency attacks, hash identification + cracking, RSA factoring (trial/Fermat/Pollard rho/Wiener) with decryption, file forensics (magic bytes, entropy, embedded carving), strings, stego checks, PCAP analysis, De Bruijn cyclic offsets, payload cheatsheets, and CTF web probes (SSTI/LFI/command injection). Offline analysis runs without an engagement; pentest_ctf_init(target) creates a scoped engagement for a challenge box in one call.

Security model

1. Authorization first. The engagement file must contain a written authorization statement and validity dates. After expiry, every active tool stops.
2. Strict scope. Only scope.domains / cidrs / ips / urls may be touched. scope.excluded always wins, and resolved IPs outside the scope are refused too.
3. No DoS. Per-target rate limits, capped port/path/credential lists, and destructive Metasploit modules are blocked while rules.no_dos is set.
4. Layered exploitation. check mode first; msf_run and payload_generate require rules.allow_payload_execution = true and a confirm_phrase equal to the engagement_id. credential_test requires its own rules.credential_testing = true flag.
5. Audit trail. Every tool call lands in audit.jsonl; findings are stored in findings.jsonl with IDs and status (open/verified/false-positive); discovered assets accumulate in assets.json.
6. Sensitive data. Credentials, tokens and personal data are reported as location + type with the value [REDACTED] — including inside evidence snippets.

Install

Requires Python 3.10+. External tools are optional: when missing, the related tool reports available: false and the built-in capabilities (TCP port scan, TLS audit, header audit, crawl, reflection, CORS, JWT) keep working.

pipx install pentester-mcp          # recommended: isolated per user
# or
uvx --from pentester-mcp pentest-mcp --version
# or
pip install --user pentester-mcp

Naming note: the PyPI package is pentester-mcp (the name pentest-mcp is blocked by PyPI's similarity guard because pentestmcp/mcp-pentest exist), while the command you run and the GitHub repo stay pentest-mcp.

From source:

cd pentest-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Optional external tools and API keys:

brew install nmap nuclei sqlmap sslscan nikto ffuf metasploit wpscan testssl hydra
# sudo apt-get install nmap sqlmap sslscan nikto ffuf metasploit-framework testssl.sh hydra

export SHODAN_API_KEY=...       # pentest_osint_shodan
export NVD_API_KEY=...          # raises NVD rate limits
export ZAP_API_URL=http://127.0.0.1:8080
export ZAP_API_KEY=...
export BURP_API_URL=https://127.0.0.1:1337
export BURP_API_KEY=...
export BURP_AUTH_STYLE=bearer   # or 'apikey' for X-API-Key
export DEFECTDOJO_URL=https://dojo.example.com
export DEFECTDOJO_API_KEY=...

Burp and ZAP report import needs no API at all — export from the GUI, then call pentest_burp_import(path) or pentest_zap_import(path).

Register with your AI agent

One command (recommended)

pentest-mcp --install detects the agents installed on your machine and writes the MCP entry into each of their configs:

pentest-mcp --list-agents           # see what was detected
pentest-mcp --install --dry-run     # preview, writes nothing
pentest-mcp --install               # register everywhere
pentest-mcp --install --project     # also write .mcp.json in the current repo
pentest-mcp --uninstall             # remove the entry again

Supported auto-detection: Claude Code (user + project scope), Claude Desktop, Cursor, Windsurf, Cline, Roo Code, Zed, OpenCode, Continue. Existing config entries are preserved; re-running is idempotent. Restart the agent afterwards.

Manual per-agent config

claude mcp add pentest-mcp -- $(which pentest-mcp)

{ "mcpServers": { "pentest-mcp": { "command": "pentest-mcp" } } }

{ "mcp": { "pentest-mcp": { "type": "local", "command": ["pentest-mcp"] } } }

{ "mcpServers": { "pentest-mcp": { "command": "pentest-mcp" } } }

{ "context_servers": { "pentest-mcp": { "command": { "path": "pentest-mcp", "args": [] } } } }

mcpServers:
  pentest-mcp:
    command: pentest-mcp
    args: []

Skill pack

The agent skills ship inside the package — export them into your agent's skills directory:

pentest-mcp --export-skills ~/.claude/skills      # Claude Code, global
pentest-mcp --export-skills .claude/skills        # per project

• pentest-guardrails — engagement rules: authorization, scope, no-DoS, sensitive-data handling, when to refuse.
• pentest-workflow — end-to-end methodology: recon → OSINT → scan → web → exploit → report.

Engagement file

No engagement file, no active tools. Generate a starter and edit it:

pentest-mcp --export-engagement-template engagement.json

Key fields:

• authorization — written authorization statement plus valid_from / valid_until
• scope.domains/ips/cidrs/urls — the only targets allowed; excluded always wins
• rules.active_scanning — true when traffic may be sent to the target
• rules.exploit_authorized / allow_payload_execution / credential_testing — keep false unless explicitly agreed in the RoE
• evidence_dir — where findings, audit trail and reports are written

Usage

Tell your agent:

Run a security assessment against https://app.example.com, engagement file: ./engagement.json

The agent loads the engagement first, then works the methodology from the pentest-workflow skill. Outputs land in evidence_dir:

• findings.jsonl, audit.jsonl, assets.json
• report-*.md, report-*.html, findings-*.sarif, findings-*-generic.json

Publish publicly

Once published, anyone in the world can install and self-register with two lines:

uv tool install pentester-mcp    # or: pipx install pentester-mcp
pentest-mcp --install

Maintainer — one-time setup and release flow:

1. Push the repository to GitHub/GitLab as keselyoleren/pentest-mcp and fill in [project.urls] in pyproject.toml. The PyPI project name is pentester-mcp (pentest-mcp itself is blocked by PyPI's similarity guard against the existing pentestmcp/mcp-pentest projects).

2. Configure PyPI Trusted Publishing (recommended, no long-lived token): pypi.org → project pentester-mcp → Publishing → add a pending publisher with your repo and workflow release.yml, environment pypi. Alternative: create a PyPI API token and use twine upload with __token__.

3. Dry-run on TestPyPI before going public:

   python -m build
   twine upload --repository testpypi dist/*
   uv tool install --index-url https://test.pypi.org/simple/ pentester-mcp
   

4. Release with a tag — CI (.github/workflows/release.yml) runs the tests, publishes to PyPI, and attaches the wheel to a GitHub Release:

   git tag v0.3.0 && git push origin v0.3.0
   

   Manual fallback: python -m build && twine upload dist/*

Distribution without PyPI works too and keeps the same user experience:

pipx install git+https://github.com/keselyoleren/pentest-mcp.git
uv tool install --from git+https://github.com/keselyoleren/pentest-mcp.git pentest-mcp

End users never need the repository: the wheel carries the MCP server, the skills (pentest-mcp --export-skills), and the engagement template (pentest-mcp --export-engagement-template). Pair public distribution with the authorization gates in the security model — the tools refuse out-of-scope targets no matter where the package came from.

Team distribution

The model: every tester runs their own local instance — perfect isolation per process, each with their own engagement file and evidence, no shared server to operate or defend. Distribute through any channel from "Publish publicly" above.

Team member onboarding (5 minutes):

pipx install pentester-mcp==0.3.0
pentest-mcp --install
pentest-mcp --export-skills ~/.claude/skills
pentest-mcp --export-engagement-template engagement.json
# edit engagement.json, then: pentest_load_engagement

Suggested team conventions:

• One engagement file per project per operator; never share engagement files across projects (scope and validity dates differ).
• Keep evidence_dir in the team's internal version control or shared storage.
• Consolidate findings across operators in DefectDojo (pentest_defectdojo_export) — the single shared source of truth in this model.
• Pin versions on deploy so tool behaviour stays consistent across the team.

Repository layout

pentest-mcp/
├── pyproject.toml              # PyPI metadata, pentest-mcp entry point
├── LICENSE
├── src/pentest_agent/
│   ├── engagement.py           # scope matching + authorization gate
│   ├── state.py                # gate() used by every tool
│   ├── runner.py               # bounded binary execution + rate limiter
│   ├── audit.py                # append-only audit trail
│   ├── findings.py             # finding model + JSONL store
│   ├── assets.py               # asset inventory (hosts, services, tech)
│   ├── patterns.py             # secret/endpoint patterns + redaction
│   ├── installer.py            # --install agent auto-detection
│   ├── engagement.example.json # bundled engagement template
│   ├── server.py               # 80 MCP tools + onboarding CLI
│   ├── skills/                 # bundled into the wheel
│   │   ├── pentest-guardrails/SKILL.md
│   │   └── pentest-workflow/SKILL.md
│   └── tools/
│       ├── recon.py            # DNS, WHOIS, subdomains, port scan, fingerprint
│       ├── osint.py            # crt.sh, Wayback, JS secrets, cloud, takeover, Shodan
│       ├── vulnscan.py         # nmap(+presets), nuclei, TLS, testssl, wpscan, CVE lookup
│       ├── webapp.py           # headers, crawl, dirbust, reflection, params, CORS,
│       │                       # JWT, open redirect, host header, secrets, sqlmap
│       ├── exploit.py          # searchsploit, Metasploit check/run, msfvenom, hydra
│       ├── ctf.py              # CTF: encodings, crypto, RSA, forensics, stego, pwn, probes
│       ├── orchestrate.py      # assess_web, attack_surface
│       ├── integrations.py     # Burp, OWASP ZAP, DefectDojo
│       └── report.py           # findings, Markdown/HTML/SARIF/generic JSON, CVSS, remediation
└── tests/                      # 64 tests: scope, gates, redaction, CVSS, SARIF, JWT,
                                # integrations, CLI, installer, CTF

Development

pip install -e ".[dev]"
pytest

Probe the tool surface without an agent:

npx @modelcontextprotocol/inspector $(which pentest-mcp)

Usage restrictions

This plugin is for security assessments that are authorised in writing. Testing systems without authorization is a criminal offence in most jurisdictions, including under Indonesia's ITE Law. The in-code scope gates limit accidental damage, but legal responsibility stays with the operator and their organisation.