{
  "markdown": "<!-- mcp-name: io.github.rijul170/qualys-mcp -->\n\n# Qualys MCP\n\n> A [Model Context Protocol](https://modelcontextprotocol.io) server for **full Qualys portal management** — expose VMDR, Policy Compliance, WAS, Cloud Agent, Container Security, TotalCloud, Patch Management, CSAM/GAV, EASM and administration to any MCP‑capable client (Claude, and other MCP hosts).\n\n<p>\n  <a href=\"https://github.com/rijul170/qualys-mcp/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/rijul170/qualys-mcp/actions/workflows/ci.yml/badge.svg\"></a>\n  <img alt=\"Python\" src=\"https://img.shields.io/badge/python-3.11%2B-blue.svg\">\n  <img alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-green.svg\">\n  <img alt=\"MCP\" src=\"https://img.shields.io/badge/MCP-server-black.svg\">\n  <img alt=\"Tools\" src=\"https://img.shields.io/badge/tools-400%2B-orange.svg\">\n</p>\n\nOne process per Qualys console (run as many as you have subscriptions). Built on\n[FastMCP](https://github.com/jlowin/fastmcp), with a single client that speaks all\nthree Qualys API families, a strict read / write / destructive safety model, and\ncredentials that never touch chat or plaintext.\n\n---\n\n## Highlights\n\n- **Broad coverage** — 59 auto‑discovered feature modules spanning the whole\n  portal: VMDR, PC, WAS, Cloud Agent, Container Security, TotalCloud/CloudView,\n  Patch Management, CSAM/GAV, EASM, FIM, EDR, PCRS, and administration.\n- **~400 tools** — `list_hosts`, `list_host_detections`, `launch_scan`,\n  `search_was_findings`, `list_knowledgebase`, `get_cs_image_vulnerabilities`,\n  and hundreds more, each mapped 1:1 to a documented Qualys API operation.\n- **Three API regimes, one client** — the classic \"FO\" XML API, the QPS REST\n  API, and the JWT‑authenticated Gateway are all handled behind `self._fo` /\n  `self._qps` / `self._gateway`.\n- **Safety tiers are load‑bearing** — every tool is annotated read‑only, write,\n  or destructive. Destructive tools (delete / purge / deactivate) are **not even\n  registered** unless you opt in per console, and still require a per‑call\n  confirmation token.\n- **Lazy auth** — no network calls at import or construction; `--check` runs\n  fully offline with no credentials.\n- **Secrets stay secret** — on Windows, credentials live only in DPAPI‑encrypted\n  blobs; on any OS you can supply them via environment variables. Nothing is ever\n  written to the repo.\n\n## The three API regimes\n\n| Regime | Base path | Auth | Payload |\n|---|---|---|---|\n| Classic \"FO\" | `/api/2.0/fo/`, `/msp/` | Basic + `X-Requested-With` header | form → XML |\n| QPS REST | `/qps/rest/` | Basic | XML `<ServiceRequest>` / JSON |\n| Gateway | `gateway.<pod>.apps.qualys.com` | Bearer JWT (from `/auth`) | JSON |\n\n## Architecture\n\n```\nqualys_mcp/\n  server.py     FastMCP server; lazy auth; --check offline validation\n  registry.py   auto-discovers modules/*.py\n  client.py     one client, three API regimes (FO / QPS / Gateway-JWT)\n  config.py     per-console config + platform (POD) -> URL map\n  common/       auth (HTTP mw), errors, logging, rate_limit, utils, xml\n  modules/      base.py + one file per feature module (the bulk of the surface)\n```\n\nAdding a capability is just dropping a file in `qualys_mcp/modules/` — see\n[docs/MODULE_BUILD_GUIDE.md](docs/MODULE_BUILD_GUIDE.md).\n\n## Quick start\n\n### 1. Install\n\n```bash\npython -m venv .venv\n# Windows:      .\\.venv\\Scripts\\pip install -e .\n# macOS/Linux:  ./.venv/bin/pip install -e .\n```\n\n### 2. Offline sanity check (no credentials required)\n\n```bash\npython -m qualys_mcp --check\n```\n\nLists every discovered module with its tool count and exits — a good first\nsmoke test.\n\n### 3. Provide credentials\n\nYou need a Qualys **API user** and your platform/POD code (e.g. `US1`, `US2`,\n`EU1`; find it under your console URL or **Help → About**).\n\n**Any OS — environment variables:**\n\n```bash\nexport QUALYS_USERNAME='api-user'\nexport QUALYS_PASSWORD='api-pass'\nexport QUALYS_PLATFORM='US2'          # or set QUALYS_API_URL / QUALYS_GATEWAY_URL\npython -m qualys_mcp --transport streamable-http --host 127.0.0.1 --port 8781 --console-label consulting\n```\n\n**Windows — DPAPI‑encrypted blobs (recommended for a persistent deployment):**\n\n```powershell\n# Encrypt once per console; the blob is user-scoped and stored under .secrets/\n.\\encrypt-qualys-creds.ps1 -Console consulting -Platform US2\n.\\encrypt-qualys-creds.ps1 -Console cloud      -Platform US2\n\n# Launch one instance per console (:8781, :8782)\n.\\start-qualys-mcp.ps1\n#   ...opt into destructive tools for a console only when you mean it:\n.\\start-qualys-mcp.ps1 -EnableDestructive cloud\n\n# Optional: keep both alive across reboots via a Scheduled Task watchdog\n.\\register-qualys-mcp-task.ps1\n```\n\nSee [.env.example](.env.example) for every `QUALYS_*` setting.\n\n### 4. Point your MCP client at it\n\nA ready‑to‑use [`.mcp.json`](.mcp.json) is included for Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"qualys-consulting\": { \"type\": \"http\", \"url\": \"http://localhost:8781/mcp\" },\n    \"qualys-cloud\":      { \"type\": \"http\", \"url\": \"http://localhost:8782/mcp\" }\n  }\n}\n```\n\n`scripts/register_mcp_clients.py` shows how to register the same local‑HTTP\nservers into several MCP clients at once.\n\n## Safety model\n\n- Tools are annotated **read‑only**, **write**, or **destructive**.\n- Destructive tools (delete, purge, deactivate, uninstall) are **not registered**\n  unless the console runs with `QUALYS_ENABLE_DESTRUCTIVE=true`.\n- Even when enabled, each destructive tool requires a matching `confirm=<id>`\n  argument before it will act — so a destructive call can never happen by\n  accident from a single prompt.\n\nRead [docs/SAFETY_AUDIT.md](docs/SAFETY_AUDIT.md) for the full tiering.\n\n## Module & tool inventory\n\n- **59 modules** auto‑discovered from `qualys_mcp/modules/`.\n- **~360 tools** registered by default; **~400** with\n  `QUALYS_ENABLE_DESTRUCTIVE=true` (the extra ~40 are the guarded destructive\n  tools that otherwise stay hidden).\n- Spread across the three API regimes, with a handful of modules spanning two.\n\nThe full per‑module table (registry name, API family, tool counts, one‑line\ndescription) is in [docs/MODULE_INDEX.md](docs/MODULE_INDEX.md), and a complete\nendpoint → tool → action breakdown is in\n[docs/ENDPOINTS_TOOLS_ACTIONS.md](docs/ENDPOINTS_TOOLS_ACTIONS.md).\n\n## Configuration reference\n\n| Variable | Purpose |\n|---|---|\n| `QUALYS_USERNAME` / `QUALYS_PASSWORD` | API user credentials |\n| `QUALYS_PLATFORM` | POD code (`US1`…`KSA1`) — auto‑fills API + Gateway URLs |\n| `QUALYS_API_URL` / `QUALYS_GATEWAY_URL` | Explicit overrides for unlisted PODs |\n| `QUALYS_CONSOLE_LABEL` | Names the console in logs and the server name |\n| `QUALYS_ENABLE_DESTRUCTIVE` | `true` to register the destructive tier |\n| `QUALYS_MCP_MODULES` | Comma‑separated allowlist to scope a console to its licensed modules |\n| `QUALYS_MCP_API_KEY` | Optional shared secret for the HTTP transport |\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npython -m qualys_mcp --check   # offline validation\npytest                          # unit tests (no network)\nruff check .                    # lint\n```\n\nContributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Disclaimer\n\nThis is an independent, community project. It is **not affiliated with,\nendorsed by, or supported by Qualys, Inc.** \"Qualys\" and product names are\ntrademarks of their respective owners. Use against your own subscriptions in\naccordance with your Qualys license and API terms. The software is provided\n\"as is\" (see [LICENSE](LICENSE)); you are responsible for what you run against\nyour environment — especially the destructive tier.\n\n## Star history\n\n<a href=\"https://star-history.com/#rijul170/qualys-mcp&Date\">\n  <img alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=rijul170/qualys-mcp&type=Date\">\n</a>\n\n## License\n\n[MIT](LICENSE) © 2026 Rijul Sharma\n",
  "bytes": 7841,
  "sha": "6c078517097932a272ae53eb1797b801e9fc6e8067336b694fc9764a377a2322",
  "repo_slug": "rijul170/qualys-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rijul170_qualys_mcp_5e7982dd/readme"
}