# qualys-pci-mcp

A read-only [MCP](https://modelcontextprotocol.io) 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`](https://docs.astral.sh/uv/)
- A Qualys **PCI merchant account** with API access

## Installation

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

```sh
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:

```sh
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`.


```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`](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](docs/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`](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`](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](LICENSE).

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.