qualys-pci-mcp

A read-only MCP server for the Qualys PCI Merchant API. It lets an LLM assistant answer questions about your PCI compliance posture, so that weekly compliance chores stop being a manual trawl through the Qualys console.

Description

This project exposes the PCI Merchant API's read endpoints as MCP tools, so you can ask questions in plain language instead:

• "Which hosts are failing PCI right now?"
• "List the confirmed-high findings that aren't already accepted false positives."

AI Disclosure

This project is very much vibe-coded in anger, to solve particular needs. As always, inspect the source code.

Requirements

• Python 3.11+
• uv
• A Qualys PCI merchant account with API access

Installation

Not published to PyPI yet, so install from a clone:

git clone https://github.com/RobotDisco/qualys-pci-mcp && cd qualys-pci-mcp
uv tool install .

Or run it straight from the checkout without installing:

uv sync && uv run qualys-pci-mcp

Then register it with your MCP client. For Claude Desktop on MacOS, place it in ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "qualys-pci": {
      "command": "/Users/you/.local/bin/qualys-pci-mcp",
      "env": {
        "QUALYS_PCI_USERNAME": "your-pci-username",
        "QUALYS_PCI_PASSWORD": "your-pci-password"
      }
    }
  }
}

Configuration

Variable	Required	Default
QUALYS_PCI_USERNAME	yes	—
QUALYS_PCI_PASSWORD	yes	—
QUALYS_PCI_BASE_URL	no	https://pci-api.qualys.com
QUALYS_PCI_DOWNLOAD_DIR	no	~/.local/share/qualys-pci-mcp/downloads — where scan-report PDFs are saved

Missing or partial credentials fail at startup, not mid-request — so you find out when you launch, not halfway through a compliance report.

Usage

As an MCP server

Once registered, ask your assistant directly:

Which hosts are currently failing PCI?

Tools

Tool	What it returns
pci_list_assets	Declared in-scope IPs, DNS hostnames, and virtual hosts
pci_compliance_summary	Per-host PCI Pass/Fail — the main way to iterate hostnames
pci_list_vulns	Vulnerability detections, compact rows
pci_get_vuln	One detection in full
pci_list_scans / pci_get_scan	Scan history and per-scan metadata
pci_download_scan_report	Saves a scan's PDF report; returns the path. Usually 404s — reports must be generated in the Qualys console first, and generation is a write operation this server does not perform

Support

Open an issue on the repository. When reporting an API problem, please include the endpoint, the parameters you used, and the HTTP status — never your credentials, and note that Qualys error bodies can echo request parameters.

Contributing

Contributions welcome. Before opening a PR:

• Read CLAUDE.md. Its invariants are not style preferences — two of them (never retry a 401, never write to stdout) prevent a locked audit account and a silently corrupted MCP stream respectively.
• Read the relevant ADR. If your change contradicts one, that's fine, but it needs a superseding ADR rather than an edit to the existing one.
• just check must pass — lint, formatting, mypy --strict, and tests. CI runs the same recipe. just recipes are listed with just; see the justfile if you would rather run the underlying commands directly.
• Never add an endpoint path that hasn't been verified against live documentation. Guessed paths are the single most likely source of confidently-broken code in this codebase. docs/reference/pci-api.md records which paths are verified, which are documentation-only, and which documented details turned out to be wrong.

Acknowledgements

The API reference was reconstructed from Qualys's published documentation at docs.qualys.com/en/pci/api/. Qualys is a trademark of Qualys, Inc.; this project is unaffiliated.

License

Apache-2.0.

Chosen over MIT for its explicit patent grant and contributor terms, which matter for a tool that wraps a commercial vendor's API, and over GPLv3 because MCP's process boundary means copyleft could not reach the integrations it would most plausibly be intended to govern.