cyver-mcp 0.4.1

MCP server exposing the Cyver reporting platform to Claude via the cyver-reporting wrapper.

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 30 tools across reads, writes, and a single gated destructive write.

Features

• 18 read tools (always on): projects, findings, clients, users, teams, client assets, plus reference data (vulnerability types, report templates, project templates), finding-library lookups, and a binary-file download tool that 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.
• 11 write tools (opt-in via CYVER_ALLOW_WRITES=1): create findings (from scratch or from a library template, with inline evidence), append evidence to existing findings, change finding status non-destructively, create / move projects, create clients and assets, attach users / assets / teams to projects, upload binary evidence files.
• 1 destructive write (additionally CYVER_ALLOW_DESTRUCTIVE=1): update_finding, a full PUT that overwrites every field not re-supplied. For status-only changes use the non-destructive update_finding_status instead.
• 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.

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: [e-mail]
Password: ********
Enable write tools (create findings, projects, etc.)? [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.

To wipe the cache:

cyver-mcp logout

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 (18, always registered)

Tool	Purpose
search_projects	Filter projects by client, status, or name.
get_project	Full detail for one project.
list_project_report_versions	Versions of the project's report.
list_project_checklists	Checklists associated with a project.
list_project_compliance_norms	Compliance norms attached to a project.
search_findings	Filter by project, status, severity, type, client, or free-text. Includes severityLabel and statusLabel.
get_finding	Full finding detail (evidence included by default).
search_clients	Filter clients by name/status.
get_client	Full client detail.
list_client_assets	Assets owned by a client.
search_users	Filter users by name, client, or role.
search_teams	Filter teams by name, client, or project.
list_vulnerability_types	Vulnerability type catalog.
list_report_templates	Available report templates.
list_project_templates	Available project templates (used by create_project auto-resolve).
list_finding_libraries	Finding-library catalog.
list_finding_templates	Templates inside a library.
download_project_file	Fetch a project file's bytes; returns an inline image content block for image/* MIMEs.

Writes (11, 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).

Tool	Purpose
create_finding	Create a finding on a project (with optional inline evidence; supports template_id for from-template creation).
update_finding_status	Change a finding's status without touching anything else (load-modify-save).
add_evidence_to_finding	Append evidence records to an existing finding (true add).
create_project	Create a project for a client.
update_project_status	Move a project (ONBOARDING / TESTING / REPORTING / REMEDIATION / COMPLETED).
create_client	Create a new client.
create_client_asset	Create an asset under a client.
add_users_to_project	Append users (true add, no replace).
add_assets_to_project	Append assets (true add, no replace).
add_teams_to_project	Append teams (true add, no replace).
upload_evidence_to_project	Upload a binary file (screenshot, PoC, etc.) as project evidence.

Every write tool accepts dry_run=True and emits one audit-log line per call.

Destructive writes (1, additionally CYVER_ALLOW_DESTRUCTIVE=1)

Tool	Purpose
update_finding	Full PUT update of an existing finding. Overwrites every field not re-supplied, replaces evidence list when supplied.

For status-only changes prefer update_finding_status (non- destructive, only needs CYVER_ALLOW_WRITES).

Configuration

Environment variables

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

Variable	Required	Purpose
CYVER_PORTAL	yes	Portal hostname, e.g. app.cyver.io.
CYVER_USERNAME	preferred	Cyver username or email. Primary auth path.
CYVER_PASSWORD	preferred	Used with CYVER_USERNAME.
CYVER_API_KEY	optional	Static API key. Leave blank to use username/password.
CYVER_SESSION_TYPE	optional	pentester (default) or client.
CYVER_ALLOW_WRITES	optional	1 to register the 11 write tools. Default: off.
CYVER_ALLOW_DESTRUCTIVE	optional	1 to also register update_finding. Has no effect without CYVER_ALLOW_WRITES=1.
CYVER_AUDIT_LOG	optional	Path to append audit-log JSON lines. Default: stderr.
CYVER_CONFIG	optional	Override the .env search path.

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.