io.github.integsec/turbopentest

@turbopentest/mcp-server

MCP server for TurboPentest — launch AI-powered penetration tests, review vulnerability findings, and generate security reports, all without leaving your coding assistant.

What it does

Ask your AI assistant to run a pentest, check progress, and walk you through remediation — the server handles all the API calls. Every completed scan is anchored to the blockchain, giving you a tamper-proof attestation you can share with customers or auditors.

Quick start

1. Get your API key

Sign up and create an API key at turbopentest.com/settings/api-keys.

2. Verify a domain

Before scanning, verify that you own the target domain at turbopentest.com/domains.

3. Add the server to your MCP client

Claude Code (.mcp.json in your project root):

{
  "mcpServers": {
    "turbopentest": {
      "command": "npx",
      "args": ["@turbopentest/mcp-server"],
      "env": {
        "TURBOPENTEST_API_KEY": "tp_live_..."
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "turbopentest": {
      "command": "npx",
      "args": ["@turbopentest/mcp-server"],
      "env": {
        "TURBOPENTEST_API_KEY": "tp_live_..."
      }
    }
  }
}

Cursor (Settings > MCP Servers > Add):

{
  "command": "npx",
  "args": ["@turbopentest/mcp-server"],
  "env": {
    "TURBOPENTEST_API_KEY": "tp_live_..."
  }
}

OpenAI Codex CLI (~/.codex/config.toml, or run codex mcp add turbopentest -- npx @turbopentest/mcp-server and set the env var when prompted):

[mcp_servers.turbopentest]
command = "npx"
args = ["@turbopentest/mcp-server"]

[mcp_servers.turbopentest.env]
TURBOPENTEST_API_KEY = "tp_live_..."

Then run /mcp inside Codex to confirm turbopentest is listed. Codex's MCP client doesn't support the "prompts" primitive, so the four guided workflows are also exposed as plain tools (turbopentest_workflow_*, see below) and described in this repo's AGENTS.md, which Codex reads automatically.

Example session

You:    "Run a standard pentest on staging.example.com"
Claude: Checks domain is verified, confirms credit balance,
        calls start_pentest → "Started tp_abc123, 4 agents, ~1 hour"

You:    "Any findings yet?"
Claude: Calls get_pentest → "62% complete — 3 findings (1 high, 2 medium)"

You:    "Show me the high severity ones"
Claude: Calls get_findings(severity: "high") →
        [1] HIGH: SQL Injection in /api/search
            CVSS: 8.6 (AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N)
            CWE: CWE-89
            PoC: POST /api/search?q=' OR 1=1--
            Remediation: Use parameterized queries...
            Retest: sqlmap -u "https://staging.example.com/api/search" ...

You:    "Give me a prioritized remediation plan"
Claude: Uses the analyze_findings prompt → produces a full markdown
        remediation plan grouped by severity and effort

White-box scanning

Pass a GitHub repository URL to start_pentest to enable white-box mode. In addition to black-box testing, the scan will include:

• SAST — static code analysis for common vulnerability patterns
• Secret detection — leaked API keys, credentials, and tokens in source
• SCA — dependency audit for known CVEs

You:  "Pentest staging.example.com, the repo is github.com/myorg/myapp"

Tools

Tool	Description
turbopentest_start_pentest	Launch a pentest against a verified domain. Supports four tiers and optional GitHub repo for white-box scanning.
turbopentest_get_pentest	Get scan status, progress, findings summary, executive summary, attack surface map, and STRIDE threat model.
turbopentest_list_pentests	List all pentests with status and finding counts. Filterable by status.
turbopentest_get_findings	Retrieve structured findings with severity, CVSS, CWE, OWASP category, PoC, remediation steps, and retest commands. Filterable by severity.
turbopentest_download_report	Download a report in markdown (best for AI), JSON, or PDF format.
turbopentest_get_credits	Check your credit balance and available scan tiers with pricing.
turbopentest_verify_attestation	Verify a blockchain-anchored attestation by SHA-256 hash. No API key required — public endpoint.
turbopentest_list_domains	List your verified domains and their verification status.
turbopentest_workflow_run_pentest	Returns the run_pentest workflow instructions as tool output (for clients without prompts support, e.g. Codex).
turbopentest_workflow_analyze_findings	Returns the analyze_findings workflow instructions as tool output.
turbopentest_workflow_compare_pentests	Returns the compare_pentests workflow instructions as tool output.
turbopentest_workflow_security_posture	Returns the security_posture workflow instructions as tool output.

Security note: turbopentest_start_pentest checks domain verification itself before calling the API — it will refuse (isError: true) to launch against a target whose domain isn't verified on your account, rather than relying solely on the agent to check first.

Prompts

Built-in prompts guide your AI assistant through multi-step workflows. Invoke them by name in any MCP client that supports prompts (Claude Code, Claude Desktop, Cursor). In clients that only support tools (Codex), use the matching turbopentest_workflow_* tool above instead — the text is identical.

Prompt	Equivalent tool	Description
run_pentest	turbopentest_workflow_run_pentest	Full-lifecycle pentest: domain check → credit verification → launch → progress monitoring → findings summary → report download
analyze_findings	turbopentest_workflow_analyze_findings	Deep-dive analysis of a single pentest's findings, producing a prioritized remediation plan with effort estimates and retest commands
compare_pentests	turbopentest_workflow_compare_pentests	Diff two pentests on the same target — shows what's new, what's been fixed, and what's still unresolved
security_posture	turbopentest_workflow_security_posture	Executive briefing across your 5 most recent pentests: risk trends, highest-risk targets, and top 3 recommended actions

Scan tiers

Tier	Agents	Duration	Price
Recon	1	~30 min	$49
Standard	4	~1 hour	$99
Deep	10	~2 hours	$299
Blitz	20	~4 hours	$699

Default tier is standard. Use recon for a quick surface sweep or blitz for maximum coverage on critical assets.

Blockchain attestation

Every completed pentest is anchored on-chain as a tamper-proof attestation. The SHA-256 hash is included in the report and can be independently verified — by you, your customers, or auditors — with no API key required:

You:  "Verify attestation abc123def456..."

turbopentest_verify_attestation returns the scan metadata (tier, agents, duration, risk score, findings summary) alongside the blockchain proof (chain ID, transaction hash, block number, merkle root).

Configuration

Variable	Required	Default	Description
TURBOPENTEST_API_KEY	Yes	—	API key from turbopentest.com/settings/api-keys
TURBOPENTEST_API_URL	No	https://turbopentest.com/api	Override the API base URL (for testing)

Requirements

• Node.js 18+
• A TurboPentest account with at least one verified domain

Using with OpenAI Codex

See docs/CODEX.md for the full Codex guide — configuration, the tool list, the authorization model, and why the guided workflows are exposed as turbopentest_workflow_* tools instead of MCP prompts.

Privacy & support

• Privacy policy: https://turbopentest.com/privacy
• Subprocessors: https://turbopentest.com/subprocessors
• Support: open a case at https://turbopentest.com/support (typically answered within a few hours on business days) or join the Discord
• Bugs in this MCP server: https://github.com/integsec/turbopentest-mcp/issues

Your API key is sent only to turbopentest.com/api as a bearer token over HTTPS. It is never logged and never transmitted anywhere else. Customer pentest content is not used to train public AI models.

License

MIT