cyver-mcp

A Model Context Protocol (MCP) server that lets Claude read from and write to the Cyver pentest reporting platform through chat. Wraps the cyver-reporting Python client and exposes 40 tools across reads, writes, and four modifications-gated tools. Findings carry OWASP Top 10 (Web + API) and checklist tags, applied through a dedicated tagging tool that reports failure rather than swallowing it, and preserved across later edits.

Features

• 22 read tools (always on): projects, findings, clients, users (search + single-user detail), teams, client assets, plus reference data (vulnerability types, report templates, project templates, per-project checklist + compliance catalogue with stable codes for tagging findings), finding-library lookups, project-file listing and download (download returns inline image content for screenshots / PoC captures).
• Auto-resolved default project template. create_project discovers "Default Pentest" by title at runtime, so callers don't need to look up or hard-code a UUID; pass an explicit project_template_id to override.
• 14 write tools (opt-in via CYVER_ALLOW_WRITES=1): create findings (from scratch or from a library template, with inline evidence, pre-emptive QA enforcement mirroring /pentest-report-review — rejects em dashes / sentinels / emojis / malformed CVE-CWE refs / severity-CVSS mismatches, requires the Background bold title to match the finding name, and is engagement-type aware (engagement_type, auto-detected from the finding content when omitted) so web / mobile / api findings get a best-guess OWASP Top 10 control suggested for review — apply it with update_finding_compliance_links — while cloud / CSA findings relax evidence / CWE / likelihood — and a dry-run preview that echoes the parent-project context before commit), append evidence, change finding status, change severity / CVSS, update client metadata, update client-asset fields, create / move projects, edit a project's Scope-tab forms (methodology / auditor-scope and pentester-assignment), create clients and assets, attach users / assets / teams to projects, upload binary evidence files. All update tools are load-modify-save (preserve every field you don't supply).
• 4 modifications-gated tools (additionally CYVER_ALLOW_MODIFICATIONS=1): update_finding_fields patches textual finding fields (name, description, recommendation, background, impact / likelihood prose, CVE / CWE / vulnerability-type / MITRE technique lists); update_finding_evidence patches a single evidence record on a finding (title, issue_details, results, reproduce, location, ip, port, protocol, version, visibility, compliance status); update_finding_checklist_links and update_finding_compliance_links tag a finding with checklist task codes (e.g. OTG-AUTHN-001) and compliance control codes (e.g. A02:2025 for OWASP Top 10 Web, API2:2023 for OWASP Top 10 API) — metadata, so these two carry no PUSH gate. All load-modify-save: only supplied fields change. Built for post-review fixes piped through /pentest-validator or /pentest-report-review skills.
• PUSH gate on the tools that write report prose: create_finding, add_evidence_to_finding, update_finding_fields and update_finding_evidence. They produce or rewrite customer-visible content, so they default to dry_run=True and require confirm="PUSH" for live writes. The user types PUSH in chat; Claude forwards the literal string. create_finding's dry-run also echoes the parent-project context (code, name, status) so users can confirm they're committing to the right project. Everything else — status, severity, compliance / checklist tags, scope, assignment — is workflow-tier: no PUSH gate, standard dry_run=False default.
• Dry-run preview on every write tool. Returns the would-be request body without sending.
• Audit log as JSON lines on every write. Default sink is stderr; set CYVER_AUDIT_LOG to a file path to also append there. Sensitive values redacted automatically.
• Severity 0..4 ↔ label and finding status 1..14 ↔ label mappings applied automatically on reads and accepted by name on writes.
• No secrets in the MCP config block. The server loads .env itself.
• Auto-reauth on token expiry. The long-lived server self-heals on a 401: it re-authenticates in place and retries the call once, so an expired session recovers with no reconnect — silently when the refresh token is still valid, or on the next call after cyver-mcp login otherwise.

Requirements

• Python 3.10 or newer
• A Cyver portal account (username + password; 2FA supported)
• Claude Desktop or Claude Code

Pure Python, runs on macOS, Linux, and Windows.

Installation

pipx install cyver-mcp

pipx is the recommended path for CLI tools. Plain pip install cyver-mcp works too if you prefer to manage your own venv.

Quick Start

One-time setup

Run the wizard. It writes ~/.config/cyver-mcp/.env (chmod 600) and primes the encrypted refresh-token cache.

cyver-mcp setup

Prompts:

Portal hostname (e.g. app.cyver.io): app.cyver.io
Username or email: you@example.com
Password: ********
Enable write tools (create findings, projects, etc.)? [y/N]: y
Enable modifications tools (patch existing finding text and evidence: update_finding_fields, update_finding_evidence)? [y/N]: y
2FA required. A code has been sent to your email.
Enter 2FA code: 123456
OK. Token cached for pentester session on app.cyver.io.

Re-authenticate later

When the cached token expires, refresh without re-running setup:

cyver-mcp login

Prompts for a 2FA code only when the wrapper raises Cyver2FARequired. Otherwise silent. A running MCP server picks up the refreshed token on its next call automatically — no reconnect or restart.

To wipe the token cache (stored credentials are kept, so cyver-mcp login signs straight back in):

cyver-mcp logout

cyver-mcp logout --forget-credentials also deletes the stored keychain credentials; signing in again then needs cyver-mcp setup in a real terminal.

To check which version is installed (run it in the same venv the MCP server uses to confirm what a spawned server is running):

cyver-mcp --version          # cyver-mcp <version>
cyver-mcp version            # + cyver-reporting and Python versions

Connect Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop. The cyver tools appear in the tool list.

Connect Claude Code

Add the same block to .mcp.json in any project where you want the tools available, then restart Claude Code in that directory.

Try it

In a new chat:

List three projects from Cyver.

Claude calls search_projects and returns three real project records. To verify writes (if enabled):

Use create_finding with dry_run=true to preview a Critical finding for project P-YYYY-NNNN about MFA missing.

You see a would_send payload back, with no actual change made on the portal.

Tools

Reads (22, always registered)

Writes (14, opt-in via CYVER_ALLOW_WRITES=1)

With the flag unset, the tools are not registered at all (Claude can't see or call them). update_finding_status and update_finding_severity are workflow-tier updates with the standard dry_run=False default. The PUSH gate applies only to update_finding_fields in the modifications tier below.

Every write tool accepts dry_run=True and emits one audit-log line per call. Update tools additionally capture per-field from/to diffs in the audit log.

Modifications (4, additionally CYVER_ALLOW_MODIFICATIONS=1)

Use these for post-review fixes from /pentest-validator or /pentest-report-review. Severity / CVSS go through update_finding_severity instead. Status goes through update_finding_status. To append NEW evidence (rather than patch an existing record), use add_evidence_to_finding. To discover which checklist task and compliance control codes a project supports, use list_project_template_catalogue.

Configuration

Environment variables

The server reads .env from $CYVER_CONFIG, then ./.env, then ~/.config/cyver-mcp/.env. Process env always wins over file values.

Username/password is the preferred path. Static API keys are supported as a fallback when one is available.

Audit log

Every write tool (live or dry-run) emits one JSON object per line:

{"ts":"2026-04-27T10:46:21Z","tool":"create_finding","target":"<project_id>","result":"ok","params":{...}}

result is one of ok, dry_run, or error:<ExceptionName>. Sensitive values (passwords, tokens, 2FA codes) are redacted before the line is written.

License

MIT.

Developed and maintained by penetration testers at Thoropass.