🛡️ CVE MCP Server
AI-powered security intelligence at your fingertips — 28 tools + a one-call triage_cve orchestrator, 24 data sources, one protocol.
A production-grade Model Context Protocol (MCP) server that turns Claude into a full-spectrum security analyst. Instead of juggling 15+ browser tabs across NVD, EPSS, CISA KEV, Shodan, VirusTotal, and GreyNoise, ask Claude one question and get correlated intelligence in seconds. Built with Python, FastMCP, httpx, aiosqlite, Pydantic v2, and defusedxml.
The problem: Triaging a single CVE means querying NVD for CVSS scores, EPSS for exploitation probability, CISA KEV for active exploitation status, GitHub for patches, and VirusTotal for malware associations — then mentally correlating everything. For 50 CVEs, that's an entire day lost.
The solution: CVE MCP Server gives Claude direct access to 28 security tools across 24 APIs — fronted by the triage_cve one-call orchestrator. Ask "Should we patch CVE-2024-3400?" and Claude fans out to every relevant source in parallel, calculates a composite risk score (with a CISA KEV hard override), and delivers a prioritized recommendation with evidence.
🌍 GARS-2026 — Global Agentic AI Readiness Survey
I'm running a global academic study measuring how ready security professionals,
developers, and enterprise teams actually are for agentic AI — MCP servers,
tool calling, governance, and human-in-the-loop workflows.
If you use this repo, your response would be a genuinely valuable data point.
📋 Take the survey (10 min):
Survey
- 60 questions · Anonymous · Supervised by SRH Berlin
- You get 50 Casky Tokens for early access to casky.ai
- Results published open access under CC-BY 4.0
📑 Table of contents
🏗️ Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ Claude Desktop / Claude Code │
│ (MCP Client via stdio) │
└──────────────────────────────┬──────────────────────────────────────┘
│ Model Context Protocol (stdio)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ CVE MCP Server (Python) │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ 27 MCP │ │ Composite │ │ SQLite Cache │ │
│ │ Tools │ │ Risk Engine │ │ + Audit Log │ │
│ └──────┬──────┘ └──────┬───────┘ └───────┬───────┘ │
│ │ │ │ │
│ ┌──────┴────────────────┴───────────────────┴──────┐ │
│ │ Async HTTP Client (httpx) │ │
│ │ Rate Limiter · Response Cache │ │
│ └──────────────────────┬───────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────────────┘
│ HTTPS (outbound only)
┌───────────────┼───────────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ VULNERABILITY│ │ NETWORK │ │ THREAT │
│ INTELLIGENCE │ │ INTELLIGENCE │ │ INTELLIGENCE │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ NVD API 2.0 │ │ AbuseIPDB │ │ VirusTotal │
│ EPSS / FIRST │ │ GreyNoise v3 │ │ MalwareBazaar│
│ CISA KEV │ │ Shodan │ │ ThreatFox │
│ OSV.dev │ │ CIRCL PDNS │ │ Ransomwhere │
│ GitHub GHSA │ │ │ │ AlienVault │
│ MITRE ATT&CK │ │ │ │ URLScan.io │
└──────────────┘ └──────────────┘ └──────────────┘
All traffic is outbound HTTPS only — no inbound ports are opened. API keys are loaded from environment variables and never logged. Private/internal IP addresses are blocked from all lookup tools.
🔍 Tool catalog (28 tools)
⭐ Orchestration (v0.2.0) — start here
| Tool | Description | API Key Required | Example Usage |
|---|
triage_cve | One-call triage that fans out NVD + EPSS + CISA KEV (+ public PoC for depth != "quick") concurrently, computes the composite risk score with a KEV hard override, falls back to VulnCheck NVD++ when NIST NVD is throttled, and on depth="deep" emits the SSVC v2 gated decision | Free / No key (key recommended) | triage_cve("CVE-2021-44228", depth="deep") |
Also exposed via MCP primitives — Resources: kev://catalog, epss://scores/{cve_id}, manifest://tool-hash (SHA-256 over the registered tool surface, for tamper detection). Prompts: patch_decision, compare_and_prioritize, dependency_triage.
Core Vulnerability Intelligence (8 tools)
| Tool | Description | API Key Required | Example Usage |
|---|
lookup_cve | Fetch detailed CVE record from NVD including CVSS scores, CWEs, affected products, references, and timeline | Free / No key (key recommended) | lookup_cve("CVE-2024-3400") |
search_cves | Search NVD for CVEs by keyword, product name, severity, or date range | Free / No key (key recommended) | search_cves(keyword="Apache Log4j", severity="CRITICAL") |
get_epss_score | Get EPSS exploitation probability (0–1) and percentile for one or more CVEs | Free / No key | get_epss_score("CVE-2024-3400") |
check_kev_status | Check whether a CVE appears in CISA's Known Exploited Vulnerabilities catalog | Free / No key | check_kev_status("CVE-2021-44228") |
get_cvss_details | Parse and explain a CVSS v3.1 vector string with per-metric breakdown | Free / No key | get_cvss_details("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H") |
get_cwe_info | Look up Common Weakness Enumeration details by CWE ID from embedded database | Free / No key | get_cwe_info("CWE-79") |
get_cve_references | Extract and categorize all reference links for a CVE (patches, advisories, exploits) | Free / No key (key recommended) | get_cve_references("CVE-2023-44487") |
bulk_cve_lookup | Batch-fetch details for up to 20 CVEs in a single call with parallel enrichment | Free / No key (key recommended) | bulk_cve_lookup(["CVE-2024-3400", "CVE-2023-44487"]) |
Exploit & Attack Intelligence (4 tools)
| Tool | Description | API Key Required | Example Usage |
|---|
search_exploits | Search GitHub for public proof-of-concept exploits and exploit code repositories | GITHUB_TOKEN (optional) | search_exploits("CVE-2024-3400") |
get_mitre_techniques | Map a CVE or CWE to relevant MITRE ATT&CK techniques, tactics, and mitigations | Free / No key | get_mitre_techniques("CVE-2021-44228") |
check_poc_availability | Determine if known proof-of-concept code exists for a CVE across multiple sources | GITHUB_TOKEN (optional) | check_poc_availability("CVE-2024-3400") |
get_attack_patterns | Retrieve CAPEC attack pattern details associated with a CWE or CVE | Free / No key | get_attack_patterns("CWE-89") |
Phase 3: Advanced Risk & Reporting (4 tools)
| Tool | Description | API Key Required | Example Usage |
|---|
calculate_risk_score | Compute composite 0–100 risk score using CVSS, EPSS, KEV status, and PoC availability | Free / No key (key recommended) | calculate_risk_score("CVE-2024-3400") |
generate_risk_report | Generate a formatted executive security report for one or more CVEs with recommendations | Free / No key (key recommended) | generate_risk_report(["CVE-2024-3400", "CVE-2023-44487"]) |
prioritize_cves | Rank a list of CVEs by composite risk score for triage prioritization | Free / No key (key recommended) | prioritize_cves(["CVE-2024-3400", "CVE-2023-4966", "CVE-2023-44487"]) |
get_trending_cves | Retrieve trending CVEs based on high EPSS scores and recent KEV additions | Free / No key | get_trending_cves(days=7, min_epss=0.5) |
Network Intelligence (4 tools)
| Tool | Description | API Key Required | Example Usage |
|---|
lookup_ip_reputation | Check IP address abuse history and confidence score via AbuseIPDB | ABUSEIPDB_API_KEY | lookup_ip_reputation("185.220.101.34") |
check_ip_noise | Query GreyNoise for IP scan/attack activity, classification, and associated CVEs | GREYNOISE_API_KEY | check_ip_noise("185.220.101.34") |
shodan_host_lookup | Get open ports, services, banners, and vulnerabilities for an IP via Shodan | SHODAN_API_KEY | shodan_host_lookup("8.8.8.8") |
passive_dns_lookup | Retrieve historical DNS resolution data for a domain from CIRCL Passive DNS | CIRCL_PDNS_USER + CIRCL_PDNS_PASSWORD | passive_dns_lookup("example.com") |
Threat Intelligence (4 tools)
| Tool | Description | API Key Required | Example Usage |
|---|
virustotal_lookup | Analyze file hashes, URLs, domains, or IPs against 70+ antivirus engines | VIRUSTOTAL_API_KEY | virustotal_lookup(hash="44d88612fea8a8f36de82e1278abb02f") |
search_malware | Search MalwareBazaar for malware samples by hash, tag, or signature | ABUSECH_AUTH_KEY (optional) | search_malware(tag="Emotet") |
search_iocs | Query ThreatFox for Indicators of Compromise linked to malware families | ABUSECH_AUTH_KEY (optional) | search_iocs(malware="CobaltStrike") |
check_ransomware | Look up ransomware payment addresses and transaction data from Ransomwhere | Free / No key | check_ransomware(address="bc1q...") |
DevSecOps (3 tools)
| Tool | Description | API Key Required | Example Usage |
|---|
scan_dependencies | Scan package names and versions against OSV.dev for known vulnerabilities | Free / No key | scan_dependencies(ecosystem="PyPI", packages={"requests": "2.28.0"}) |
scan_github_advisories | Search GitHub Security Advisories by ecosystem, package, or severity | GITHUB_TOKEN (optional) | scan_github_advisories(ecosystem="pip", package="django") |
urlscan_check | Submit a URL for scanning or retrieve previous scan results from URLScan.io | URLSCAN_API_KEY | urlscan_check("https://suspicious-site.com") |
🔑 API keys setup
API keys are organized by priority — get the Tier 1 keys first for maximum coverage with free tools, then progressively add Tier 2 and Tier 3 as needed.
Tier 1: High priority (free, instant access, maximum coverage)
| ENV Variable | Enables | How to Get | Free Tier Limits | Required? |
|---|
NVD_API_KEY | 10× faster NVD lookups (50 req/30s vs 5) | Request at nvd.nist.gov | 50 requests per 30 seconds | Optional but strongly recommended |
GITHUB_TOKEN | GitHub Advisory search + exploit PoC search | Create PAT at github.com/settings/tokens | 5,000 requests/hour | Optional (60/hr without) |
Tier 2: Recommended (free accounts, significant value)
Tier 3: Optional (extended intelligence)
| ENV Variable | Enables | How to Get | Free Tier Limits | Required? |
|---|
URLSCAN_KEY | URL scanning and website analysis | Sign up at urlscan.io | 5,000 public scans/day | Optional |
CIRCL_PDNS_USER | CIRCL Passive DNS lookups | Request access at circl.lu | Partner access only | Optional |
CIRCL_PDNS_PASS | CIRCL Passive DNS authentication | Provided with CIRCL registration | Partner access only | Optional |
⚡ Zero-key start: Eight tools work without any API key — EPSS, CISA KEV, OSV.dev, MITRE ATT&CK, CWE lookups, CVSS parsing, Ransomwhere, and NVD (at reduced rate). You can start using the server immediately and add keys progressively.
⚙️ Configuration
Environment variables (.env.example)
# NVD API key — free at https://nvd.nist.gov/developers/request-an-api-key
# Without key: 5 req/30s | With key: 50 req/30s
NVD_API_KEY=
# GitHub token — increases rate limit from 60/hr to 5000/hr (no scopes needed)
GITHUB_TOKEN=
# Threat intelligence keys (all optional — tools degrade gracefully without them)
ABUSEIPDB_KEY= # https://www.abuseipdb.com/account/api
VIRUSTOTAL_KEY= # https://www.virustotal.com/gui/join-us
URLSCAN_KEY= # https://urlscan.io/user/signup
SHODAN_KEY= # https://account.shodan.io/register
# GreyNoise — uses /v3/ip/{ip} endpoint (NOT the deprecated /v3/community)
GREYNOISE_API_KEY= # https://viz.greynoise.io/signup
# CIRCL Passive DNS — requires partner registration
CIRCL_PDNS_USER=
CIRCL_PDNS_PASS=
# Optional overrides
CACHE_DB_PATH= # defaults to ~/.cve-mcp/cache.db
AUDIT_LOG_PATH= # defaults to ~/.cve-mcp/audit.log
REQUEST_TIMEOUT=30 # HTTP timeout in seconds
MAX_RETRIES=3 # retries on transient errors
💬 Usage examples
Scenario 1: "Should we patch Log4Shell immediately?"
You: Analyze if CVE-2021-44228 (Log4Shell) needs immediate patching. Give me the risk score and your recommendation.
Claude orchestrates multiple tools behind the scenes:
→ lookup_cve("CVE-2021-44228")
CVSS 3.1: 10.0 (CRITICAL) | AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H
→ get_epss_score("CVE-2021-44228")
EPSS: 0.97531 (97.5%) | Percentile: 99.99%
→ check_kev("CVE-2021-44228")
✅ IN CISA KEV — Added 2021-12-10 | Known ransomware use: Yes
→ check_poc_exists("CVE-2021-44228")
✅ WEAPONIZED — 300+ public PoC repositories found
→ calculate_risk_score("CVE-2021-44228")
Risk Score: 97/100 (CRITICAL) | Urgency: PATCH IMMEDIATELY
Claude's response: "CVE-2021-44228 scores 97/100 (CRITICAL). Remote code execution in Apache Log4j, CVSS 10.0, 97.5% EPSS probability, confirmed active exploitation in CISA KEV including ransomware campaigns, 300+ public exploits. Patch immediately."
Scenario 2: "Scan my Python requirements.txt"
You: Scan these dependencies: requests==2.28.0, flask==2.2.0, django==3.2.0, pillow==9.0.0, cryptography==37.0.0
→ scan_dependencies(ecosystem="PyPI", packages={...})
Found 12 vulnerabilities across 4 packages
Claude's response: "Found 12 vulnerabilities across your packages. Immediate action: Django 3.2.0 (3 critical CVEs including SQL injection), Pillow 9.0.0 (heap overflow), cryptography 37.0.0 (OpenSSL chain). Upgrade to: django>=4.2.16, pillow>=10.3.0, cryptography>=42.0.0."
Scenario 3: "Investigate a suspicious IP"
You: Investigate suspicious IP 185.220.101.34 — is it malicious?
→ check_ip_reputation("185.220.101.34")
AbuseIPDB Confidence: 100% | Reports: 4,832 | ISP: Tor Exit Node
→ check_ip_noise("185.220.101.34")
GreyNoise: MALICIOUS | Tags: [Tor Exit Node, Web Scanner]
CVEs targeted: CVE-2024-3400, CVE-2023-46805
→ shodan_host_lookup("185.220.101.34")
Open ports: 22, 80, 443, 9001 | OS: Linux
Claude's response: "185.220.101.34 is a known Tor exit node rated 100% malicious by AbuseIPDB with 4,832 abuse reports. GreyNoise confirms active scanning for CVE-2024-3400 (Palo Alto) and CVE-2023-46805 (Ivanti). Recommendation: Block at firewall."
Scenario 4: "Generate an executive security report"
You: Generate an executive security report for: CVE-2024-3400, CVE-2023-44487, CVE-2023-4966, CVE-2024-21887
→ compare_cves([...])
Compiles: NVD, EPSS, KEV, PoC availability, MITRE ATT&CK mapping
Generates: Ranked risk table, remediation timeline, executive summary
📊 Risk score explained
The calculate_risk_score tool produces a composite risk score from 0 to 100 by weighting four independent signals.
The formula
Risk Score = (CVSS × 0.20) + (EPSS × 0.35) + (KEV × 0.30) + (PoC × 0.15)
| Component | Weight | What It Captures |
|---|
| CVSS v3.1 Base Score | 20% | Theoretical worst-case severity |
| EPSS Probability | 35% | Statistical likelihood of exploitation in the next 30 days |
| CISA KEV Status | 30% | Confirmed active exploitation in the wild |
| PoC Availability | 15% | Public exploit code lowers the barrier for attackers |
Boost multipliers
- KEV + active PoC → ×1.15
- CVSS ≥ 9.0 + EPSS > 0.7 → ×1.10
- Published < 7 days ago → ×1.05
Score is capped at 100.
Risk Scoring — v1 (2026-06)
The numeric scorer is scoring_version 1.0 (surfaced in triage_cve, calculate_risk_score, and health_check). The linear weighted sum above is the v1 default for the numeric score, with one hard override:
- CISA KEV hard override: a KEV-listed CVE is confirmed exploited in the wild, the single strongest exploitation signal. Its label can never be lower than CRITICAL and its score is clamped to ≥ 76, regardless of CVSS/EPSS. (A KEV CVE with a low CVSS and low EPSS still returns CRITICAL / 76.)
- CVSS is treated as a severity signal, not an exploitation-likelihood signal (per Allodi & Massacci 2014); EPSS and KEV carry the exploitation signal.
- An experimental SSVC v2 gated decision (CISA Deployer model →
Act / Attend / Track* / Track) is available via triage_cve(depth="deep") as a qualitative, explainable alternative to the 0–100 number.
| Score | Label | Recommended Action |
|---|
| 0 – 25 | LOW | Schedule for next maintenance window |
| 26 – 50 | MEDIUM | Patch within 30 days per SLA |
| 51 – 75 | HIGH | Patch within 7 days; escalate to team lead |
| 76 – 100 | CRITICAL | Patch within 24–48 hours. Emergency change window. |
Why these weights?
EPSS gets the highest weight (35%) because it's the single best predictor of actual exploitation — far better than CVSS alone. A CVSS 10.0 with EPSS 0.01 is theoretically dangerous but practically unlikely. KEV at 30% is ground truth: confirmed exploitation, not a prediction. CVSS at 20% captures severity context for new CVEs with insufficient EPSS data. PoC at 15% reflects that public exploits dramatically accelerate real-world attacks.
🆕 What's new in v0.2.0
triage_cve orchestrator — one tool call that fans out NVD + EPSS + CISA KEV (+ public PoC discovery for depth != "quick") concurrently, computes the composite risk score, and returns a clean report. depth is quick / standard (default) / deep; deep additionally emits the SSVC v2 gated decision.- New upstream sources — VulnCheck NVD++ (a transparent NVD fallback used automatically inside
triage_cve when NIST NVD is unreachable/throttled), CIRCL hashlookup, and the HIBP Pwned Passwords range API.
- KEV hard-override scoring +
scoring_version — KEV-listed CVEs are always CRITICAL (score ≥ 76); the scoring version is reported in triage_cve and health_check.
- HTTP transport — set
MCP_TRANSPORT=http to serve streamable-HTTP on HOST:PORT (default 0.0.0.0:8000, stateless) instead of stdio. Ships with a Dockerfile.
- Resources & prompts — resources
kev://catalog, epss://scores/{cve_id}, and manifest://tool-hash (SHA-256 over the registered tool surface); prompts patch_decision, compare_and_prioritize, and dependency_triage.
- Security posture — the server never registers a sampling handler / never issues
sampling/createMessage (Unit 42 MCP-sampling attack vector); new outbound paths are scheme/host-allowlisted.
🌐 Data sources
| # | Source | Data Provided | Auth | Rate Limit (Free) |
|---|
| 1 | NVD | CVE details, CVSS, CWEs, CPEs | apiKey header (optional) | 5 req/30s (50 with key) |
| 2 | EPSS | Exploitation probability and percentiles | None | 1,000 req/min |
| 3 | CISA KEV | Actively exploited CVE catalog | None | Static file |
| 4 | OSV.dev | Open-source package vulnerabilities | None | No published limit |
| 5 | GitHub Advisories | GHSA advisories, patches, affected versions | Bearer token | 60/hr (5,000 with PAT) |
| 6 | MITRE ATT&CK | TTPs, techniques, mitigations | None | No published limit |
| 7 | AbuseIPDB | IP abuse confidence, reports, ISP, geo | Key header | 1,000 checks/day |
| 8 | GreyNoise | IP noise/scan activity, classification | key header | 50 queries/week |
| 9 | Shodan | Open ports, services, banners, CVEs | key query param | Basic lookups |
| 10 | VirusTotal | Multi-AV scan results, reputation | x-apikey header | 500/day, 4/min |
| 11 | MalwareBazaar | Malware samples, hashes, signatures | Auth-Key header | Fair use |
| 12 | ThreatFox | IOCs linked to malware families | Auth-Key header | Fair use |
| 13 | Ransomwhere | Ransomware BTC addresses and transactions | None | No published limit |
| 14 | URLScan.io | URL scanning, screenshots, DOM | API-Key header | 5,000 public scans/day |
| 15 | CIRCL PDNS | Historical passive DNS records | HTTP Basic Auth | Partner access |
| 16 | GitHub Code Search | Exploit PoC repository search | Bearer token | Shared with GHSA limits |
| 17 | Exploit-DB | Public exploit database CSV | None | No published limit |
| 18 | Nuclei Templates | Community detection templates | None | No published limit |
| 19 | MSRC | Microsoft security advisories | None | No published limit |
| 20 | Red Hat Security | Red Hat CVE advisories | None | No published limit |
| 21 | Ubuntu Security | Ubuntu CVE tracker | None | No published limit |
| 22 | VulnCheck NVD++ | NVD-schema CVE records (transparent NVD fallback) | Bearer token (free Community) | Per VulnCheck Community tier |
| 23 | CIRCL hashlookup | Known-good file metadata (NSRL + others), hashlookup:trust | None | Best-effort |
| 24 | HIBP Pwned Passwords | Breached-password counts via k-anonymity range API | None | No hard limit |
🧪 Running tests
# Run the full test suite
pytest tests/ -v
# Run specific test files
pytest tests/test_validators.py tests/test_risk_scorer.py -v
# Run with coverage
pytest tests/ -v --cov=src/cve_mcp --cov-report=term-missing
Test with the MCP Inspector
npx @modelcontextprotocol/inspector python -m cve_mcp.server
Opens at http://localhost:6274 — interactively test each tool, view input schemas, and inspect response formats.
What tests cover
- Unit tests: Risk score calculation, CVSS vector parsing, input validation
- Integration tests: Tool registration, parameter validation, error handling for missing keys
- Cache tests: SQLite cache writes, TTL expiration, cache hit/miss
- Security tests: Private IP blocking, XML bomb protection (defusedxml), input sanitization
🏛️ Architecture deep dive
File structure
src/cve_mcp/
├── server.py # FastMCP server — all 27 @mcp.tool() definitions
├── config.py # Environment config and API base URLs
├── models.py # Pydantic models (CVERecord, KEVEntry, EPSSScore, ...)
├── audit.py # Rotating audit log (50MB, 5 backups)
├── api/
│ ├── nvd_client.py # NVD REST API v2.0
│ ├── osv_client.py # OSV.dev package vulnerability API
│ ├── epss_client.py # FIRST EPSS API
│ ├── kev_client.py # CISA KEV catalog
│ ├── ip_intel.py # AbuseIPDB + GreyNoise
│ ├── domain_intel.py # crt.sh + CIRCL passive DNS
│ ├── shodan_client.py # Shodan host intelligence
│ ├── hash_intel.py # MalwareBazaar + VirusTotal
│ ├── url_safety.py # URLScan.io
│ ├── malware_intel.py # ThreatFox IOC lookup
│ ├── ransomware_intel.py# Ransomwhere Bitcoin address lookup
│ ├── exploit_intel.py # GitHub PoC/exploit search
│ ├── vendor_advisory.py # MSRC + Red Hat + Ubuntu advisories
│ ├── attack_mapping.py # MITRE ATT&CK STIX mapping
│ ├── cve_timeline.py # CVE event timeline builder
│ ├── dependency_scan.py # OSV-based dependency scanning
│ ├── poc_checker.py # GitHub + Exploit-DB + Nuclei PoC search
│ ├── report_generator.py# Vuln report + CVE comparison matrix
│ └── rate_limiter.py # Token bucket rate limiter for NVD
├── cache/
│ └── sqlite_cache.py # Async SQLite cache with per-key TTL
└── utils/
├── validators.py # CVE ID normalization, IP/hash validation
└── risk_scorer.py # Composite risk score computation
Caching strategy
| Resource | TTL |
|---|
| CVE records (NVD) | 1 hour |
| EPSS scores | 6 hours |
| KEV catalog | 1 hour |
| IP / domain intel | 1 hour |
| Exploit-DB CSV | 24 hours |
| ATT&CK STIX data | 24 hours |
| Ransomware intel | 24 hours |
Audit log
Every tool invocation is logged to ~/.cve-mcp/audit.log:
{
"timestamp": "2026-04-14T10:23:45.123Z",
"tool": "lookup_cve",
"parameters": {"cve_id": "CVE-2024-3400"},
"duration_ms": 342,
"cache_hit": false,
"status": "ok"
}
API keys and response payloads are never written to audit logs.
🔐 Security and privacy
What data leaves your machine
- Outbound HTTPS only — no inbound ports opened, no telemetry
- CVE IDs, IPs, hashes, domains, and package names are sent to respective APIs for lookup
- API responses are cached locally in SQLite — cached data stays on your machine
Private IP blocking
All network intelligence tools block private and reserved IP ranges before any external API call:
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (RFC 1918)127.0.0.0/8 (loopback), 169.254.0.0/16 (link-local)::1, fc00::/7 (IPv6 private)
API key protection
- Keys loaded from environment variables only — never hardcoded
.env is gitignored- Keys never logged, cached, or included in audit entries
XML safety
defusedxml is used for all XML parsing to prevent XML bomb attacks (billion laughs, XXE injection).
🔧 Troubleshooting
Server won't start
# Ensure virtual environment is activated and package is installed
pip install -e .
python --version # must be 3.10+
Claude Desktop doesn't show the hammer icon (🔨)
- Check for JSON syntax errors (no trailing commas) in your config
- Use absolute paths — relative paths silently fail
- Fully quit Claude Desktop (Cmd+Q / Alt+F4) and restart
NVD rate limited
# Add your free NVD API key to .env
NVD_API_KEY=your-key-here
# https://nvd.nist.gov/developers/request-an-api-key
The server queues excess requests automatically, but with a key you get 10× throughput.
GreyNoise 401 Unauthorized
# Verify your key works:
curl -H "key: YOUR_KEY" https://api.greynoise.io/v3/ip/8.8.8.8
# The server uses /v3/ip/{ip} — NOT the deprecated /v3/community endpoint
Windows encoding issues
$env:PYTHONUTF8 = "1"
$env:PYTHONIOENCODING = "utf-8"
🗺️ Roadmap and known limitations
What the server does NOT do
- No active scanning — intelligence/lookup only, does not probe your infrastructure
- No write operations — reads from external APIs only (except URLScan submissions)
- No CVSS v4.0 scoring — built-in calculator handles v3.1 only; NVD-provided v4.0 scores are displayed but not recalculated
Known API limitations
- NVD returns max 2,000 results per query
- EPSS scores for brand-new CVEs (< 24 hours old) may not exist yet
- CISA KEV updates on US business days only
- GreyNoise community tier: 50 queries/week
- VirusTotal free tier: 4 requests/minute
- CIRCL PDNS requires manual registration and approval
- Ransomwhere has a 90-day embargo on new addresses
Planned improvements
- CVSS v4.0 local calculator
- Webhook/alerting for KEV additions and EPSS score changes on a CVE watchlist
- STIX 2.1 export for SIEM integration
- Docker container with zero-install deployment
- Streamable HTTP transport (MCP SSE)
- Additional sources: Censys, SecurityTrails, VulnCheck
🤝 Contributing
Contributions are welcome.
Adding a new tool
- Add the tool function in
server.py with the @mcp.tool() decorator
- Add input validation in
utils/validators.py
- Implement the API client in
api/
- Add tests in
tests/
- Update this README
@mcp.tool()
async def my_new_tool(param: str, ctx: Context = None) -> str:
"""
One-line description for Claude to know when to use this tool.
Args:
param: Description of the parameter
"""
app = _get_app(ctx)
# validate → cache check → API call → cache write → audit → return
Testing requirements
- All new tools must have at least one offline test with mocked responses
- Risk score changes must include formula verification test cases
- Network tools must include a test verifying private IP blocking
- All tests must pass:
pytest tests/ -v
📄 License
MIT License — see LICENSE for details.
Copyright (c) 2025-2026 Mahipal Jangra (mukul975)