🛡️ CVE MCP Server

AI-powered security intelligence at your fingertips — 27 tools, 21 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 27 security tools across 21 APIs. Ask "Should we patch CVE-2024-3400?" and Claude queries every relevant source in parallel, calculates a composite risk score, and delivers a prioritized recommendation with evidence.

---

📑 Table of contents

• Architecture
• Tool catalog
• Installation
• API keys setup
• Configuration
• Quick start
• Usage examples
• Risk score explained
• Data sources
• Running tests
• Architecture deep dive
• Security and privacy
• Troubleshooting
• Roadmap and known limitations
• Contributing
• License

---

🏗️ 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 (27 tools)

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")

---

📦 Installation

Prerequisites

• Python 3.10+ (3.11 or 3.12 recommended)
• pip or uv package manager
• Git for cloning the repository
• A terminal with access to environment variables

Step-by-step setup

# 1. Clone the repository
git clone https://github.com/mukul975/cve-mcp-server.git
cd cve-mcp-server

# 2. Create and activate a virtual environment
python -m venv venv

# macOS / Linux:
source venv/bin/activate

# Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# Windows (CMD):
venv\Scripts\activate.bat

# 3. Install dependencies
pip install -e .

# 4. Copy and configure environment variables
cp .env.example .env
# Edit .env with your API keys (see API Keys Setup section below)

# 5. Verify the server starts
python -m cve_mcp.server

Using uv (faster alternative)

git clone https://github.com/mukul975/cve-mcp-server.git
cd cve-mcp-server
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install -e .
cp .env.example .env

With test dependencies

pip install -e ".[test]"

---

🔑 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)

ENV Variable	Enables	How to Get	Free Tier Limits	Required?
ABUSEIPDB_KEY	IP reputation lookups	Register at abuseipdb.com	1,000 checks/day	Required for IP tools
VIRUSTOTAL_KEY	File/URL/domain/IP malware scanning	Sign up at virustotal.com	500 lookups/day, 4/min	Required for VT tools
GREYNOISE_API_KEY	IP noise/scan activity intelligence	Sign up at viz.greynoise.io	50 queries/week (community)	Required for GreyNoise tools
SHODAN_KEY	Host/port/service reconnaissance	Register at account.shodan.io	Basic host lookups (free tier)	Required for Shodan tools

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

Claude Desktop configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cve-mcp": {
      "command": "python",
      "args": ["-m", "cve_mcp.server"],
      "cwd": "/absolute/path/to/cve-mcp-server",
      "env": {
        "NVD_API_KEY": "your-key-here",
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx",
        "ABUSEIPDB_KEY": "your-abuseipdb-key",
        "GREYNOISE_API_KEY": "your-greynoise-key",
        "SHODAN_KEY": "your-shodan-key"
      }
    }
  }
}

⚠️ Important: Always use absolute paths. Fully quit Claude Desktop (Cmd+Q / Alt+F4) after changing the config — reloading is not enough.

Claude Code configuration

# Basic setup
claude mcp add cve-mcp -- python -m cve_mcp.server

# With environment variables from a .env file
claude mcp add cve-mcp --env-file .env -- python -m cve_mcp.server

# Verify it's connected
claude mcp list

---

🚀 Quick start

Step 1: Install (2 minutes)

git clone https://github.com/mukul975/cve-mcp-server.git
cd cve-mcp-server
python -m venv venv && source venv/bin/activate
pip install -e .

Step 2: Test with free tools first

No .env file needed. Add the server to Claude Desktop or Claude Code and try:

"What is CVE-2021-44228? Is it actively exploited?"

Claude will use lookup_cve (NVD), get_epss_score (EPSS), and check_kev (CISA KEV) — all free, no keys required.

"Scan these Python packages for vulnerabilities: requests 2.28.0, flask 2.2.0, django 3.2.0"

Step 3: Add your first key for 10× performance

echo 'NVD_API_KEY=your-key-here' > .env

Request a free NVD key at nvd.nist.gov — instant via email, increases rate limit from 5 to 50 requests per 30 seconds.

Step 4: Full power mode

Once you've added Tier 1 and Tier 2 keys:

"Calculate the risk score for CVE-2024-3400 and tell me if we should patch immediately."

---

💬 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 labels

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.

---

🌐 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

---

🧪 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

1. Add the tool function in server.py with the @mcp.tool() decorator
2. Add input validation in utils/validators.py
3. Implement the API client in api/
4. Add tests in tests/
5. 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)

---

<p align="center"> Built with 🔐 by <a href="https://github.com/mukul975">Mahipal Jangra</a> · Berlin, Germany<br> <em>Turning security intelligence into conversation.</em> </p>