┌─────────────────────────────────────────────────────────────────────┐
│                        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   │
└──────────────┘ └──────────────┘            └──────────────┘

# 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

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

pip install -e ".[test]"

# 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

{
  "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"
      }
    }
  }
}

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

# With environment variables (repeat -e for each key)
claude mcp add cve-mcp -e NVD_API_KEY=your_key -e VULNCHECK_TOKEN=your_token -- python -m cve_mcp.server
# Or just run from the project directory — python-dotenv auto-loads .env on startup

# Verify it's connected
claude mcp list

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 .

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

→ 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

→ scan_dependencies(ecosystem="PyPI", packages={...})
  Found 12 vulnerabilities across 4 packages

→ 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

→ compare_cves([...])
  Compiles: NVD, EPSS, KEV, PoC availability, MITRE ATT&CK mapping
  Generates: Ranked risk table, remediation timeline, executive summary

Risk Score = (CVSS × 0.20) + (EPSS × 0.35) + (KEV × 0.30) + (PoC × 0.15)

### 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](LICENSE) for details.

---

  Built with 🔐 by  · Berlin, Germany
  Turning security intelligence into conversation.