qualys-mcp 0.2.9

MCP server for Qualys security APIs - natural language interaction with vulnerability, asset, and cloud security data

Qualys MCP Server

⚠️ Unofficial project. This is a personal project to showcase the viability of connecting AI assistants to Qualys via the Model Context Protocol. It is not affiliated with, endorsed by, or supported by Qualys, Inc.

An MCP server that connects AI assistants to Qualys security data. 7 workflow tools covering vulnerability management, cloud security, containers, compliance, remediation, and more. Pure Python, zero config beyond credentials.

📖 Full documentation →

What's new in v0.2.9

• Streamable HTTP + Docker support — run the server as a persistent, network-reachable container instead of stdio-only (see Run with Docker below).
• Fixed per-asset detections in issue #229.
• Breaking: now requires Python ≥3.10 and fastmcp ≥2.11 — Python 3.9 installs are no longer supported.

Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "qualys": {
      "command": "uvx",
      "args": ["qualys-mcp"],
      "env": {
        "QUALYS_USERNAME": "your-username",
        "QUALYS_PASSWORD": "your-password",
        "QUALYS_POD": "US2"
      }
    }
  }
}

Set QUALYS_POD to your platform POD — the server derives the correct API and gateway URLs automatically.

Supported pods: US1 US2 US3 US4 EU1 EU2 EU3 IN1 CA1 AE1 UK1 AU1 KSA1

Advanced: If you need to override the auto-derived URLs, set QUALYS_BASE_URL and QUALYS_GATEWAY_URL explicitly instead of QUALYS_POD. Explicit URLs take priority.

Requires uv: brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh

Updating

uvx caches the resolved build, so a plain uvx qualys-mcp keeps running the version it first downloaded — it does not auto-upgrade when a new release ships. To move to the latest version, clear the cache and restart Claude Desktop:

uv cache clean qualys-mcp

To pin (and control) the version explicitly, set it in your config args:

"args": ["qualys-mcp@0.2.7"]

pip install -U qualys-mcp only updates a pip-installed copy — it has no effect on the uvx-launched server.

Alternative

pip install qualys-mcp
qualys-mcp

Self-Signed Certificates

For environments with self-signed certs, add "QUALYS_SSL_VERIFY": "false" to the env block.

Run with Docker (Streamable HTTP)

Prefer a persistent, network-reachable server over the uvx stdio setup above? Run it as a container instead:

docker build -t qualys-mcp:latest .
cp .env.example .env
$EDITOR .env                      # set your Qualys credentials
docker compose up -d
claude mcp add --transport http qualys http://127.0.0.1:8000/mcp/

See docs/DOCKER.md for the full guide: environment variables, connecting other MCP clients, security notes, and troubleshooting.

Tools

7 workflow tools that intelligently dispatch to 42 internal aggregators across all Qualys modules. Each tool handles routing, concurrent API calls, cross-domain correlation, and response synthesis automatically.

Tool	What it answers
investigate	Deep-dive any security topic — CVEs, threat actors, assets, EDR/FIM events, KB searches
assess_risk	Cross-domain risk — VMs, cloud (AWS/Azure/GCP/OCI), containers, web apps, certificates, assets
check_compliance	Compliance posture — PCI, HIPAA, CIS, NIST, SOC2 pass/fail, failing controls, exceptions
plan_remediation	Patch priorities, deployment status, mitigation coverage, program gap analysis
security_overview	Daily/weekly/monthly briefing — scanner health, scan status, vulnerability findings
reports	Generate, list, download, and manage Qualys reports
cache_status	View and clear API caches

Key Parameters

investigate

• target — CVE ID, threat actor, hostname, IP, or free-text topic
• depth — quick (~10s) / standard (~20s) / deep (~45s)
• scope — all / vulns / threats / assets / edr / fim

assess_risk

• scope — all / cloud / containers / web / certs / assets
• tag / asset_group — filter by business group
• provider — aws / azure / gcp (cloud scope)
• asset_id — single asset deep-dive

check_compliance

• framework — PCI / HIPAA / CIS / NIST / SOC2
• include_exceptions — include risk acceptances

plan_remediation

• scope — all / patches / mitigations / program
• severity — critical / high / moderate
• cves / qids — check mitigation coverage for specific vulns

security_overview

• period — today / week / month
• quick — fast snapshot (~2s) vs full briefing

Example Conversations

Daily Operations

"Give me a security overview"                  → security_overview(quick=True)
"What happened this week?"                     → security_overview(period="week")
"What should we patch first?"                  → plan_remediation(scope="patches", severity="critical")
"How's our compliance?"                        → check_compliance()

Investigation

"Tell me about CVE-2024-3400"                  → investigate(target="CVE-2024-3400")
"Are we exposed to ransomware?"                → investigate(target="ransomware")
"What do we know about Iranian threats?"        → investigate(target="iran")
"Investigate this host: 10.0.0.1"              → investigate(target="10.0.0.1", scope="edr")

Risk Assessment

"What's our overall risk?"                     → assess_risk(scope="all")
"How's our cloud security?"                    → assess_risk(scope="cloud")
"Any container vulnerabilities?"               → assess_risk(scope="containers")
"Web app security status?"                     → assess_risk(scope="web")
"Show me risk for Production assets"           → assess_risk(tag="Production")

Compliance & Remediation

"Are we PCI compliant?"                        → check_compliance(framework="PCI")
"What's our patch coverage?"                   → plan_remediation(scope="patches")
"Is there a mitigation for CVE-2024-3400?"     → plan_remediation(cves=["CVE-2024-3400"])
"What security gaps do we have?"               → plan_remediation(scope="program")

Multi-Step Workflows

"New critical CVE dropped — what do I need to know?"
→ investigate(target="CVE-...") → plan_remediation(cves=["CVE-..."]) → check_compliance()

"Prepare me for the weekly security standup"
→ security_overview(period="week") → assess_risk(scope="all") → plan_remediation(scope="patches")

"PCI audit prep"
→ check_compliance(framework="PCI", include_exceptions=True) → assess_risk(scope="all") → plan_remediation()

Architecture

AI Assistant → qualys_mcp.py (7 tools) → workflows/ (dispatch + synthesis) → aggregators.py (42 functions) → api.py (HTTP + caching) → Qualys APIs

Each workflow tool:

1. Builds a dispatch plan based on parameters
2. Runs selected aggregators concurrently
3. Merges results into a unified response envelope
4. Applies cross-domain correlation
5. Returns prioritized findings and recommended actions

Performance

Tested on an 89,000-asset environment (US2 POD):

Workflow	Time
security_overview(quick=True)	1.7s
assess_risk(scope="cloud")	1.3s
assess_risk(scope="containers")	3.1s
check_compliance()	<1ms (cached)
plan_remediation(scope="patches")	2.6s
investigate(target="CVE-2024-3400")	~33s
assess_risk(scope="all")	4.9s

Cold start: The first query after launching takes 2-10s longer while the bearer token is acquired and caches warm up. A background thread pre-fetches VMDR detections on startup. After the first query, responses are significantly faster. Ask security_overview(quick=True) first to warm caches.

Eval Harness

300 routing test questions + 900 variants + 30 multi-turn conversation workflows for automated evaluation.

# Install eval dependencies
pip install anthropic mcp python-dotenv pyyaml

# Run eval
python -m eval --quick

Testing

# Unit tests (282 tests)
pip install pytest
pytest tests/ --ignore=tests/conversations -q

# Smoke test
bash test_tools.sh fast

Qualys PODs

POD	BASE_URL	GATEWAY_URL
US1	qualysapi.qualys.com	gateway.qg1.apps.qualys.com
US2	qualysapi.qg2.apps.qualys.com	gateway.qg2.apps.qualys.com
US3	qualysapi.qg3.apps.qualys.com	gateway.qg3.apps.qualys.com
US4	qualysapi.qg4.apps.qualys.com	gateway.qg4.apps.qualys.com
EU1	qualysapi.qualys.eu	gateway.qg1.apps.qualys.eu
EU2	qualysapi.qg2.apps.qualys.eu	gateway.qg2.apps.qualys.eu
EU3	qualysapi.qg3.apps.qualys.eu	gateway.qg3.apps.qualys.eu
IN1	qualysapi.qg1.apps.qualys.in	gateway.qg1.apps.qualys.in
CA1	qualysapi.qg1.apps.qualys.ca	gateway.qg1.apps.qualys.ca
AE1	qualysapi.qg1.apps.qualys.ae	gateway.qg1.apps.qualys.ae
UK1	qualysapi.qg1.apps.qualys.co.uk	gateway.qg1.apps.qualys.co.uk
AU1	qualysapi.qg1.apps.qualys.com.au	gateway.qg1.apps.qualys.com.au
KSA1	qualysapi.qg1.apps.qualysksa.com	gateway.qg1.apps.qualysksa.com

License

MIT - Copyright (c) 2026 Andrew Nelson