# CVE Search MCP Server

A Model Context Protocol (MCP) server for CVE and vulnerability searching, optimized for PR review scenarios. Helps developers and security teams identify the latest CVEs and vulnerabilities — including those that postdate an LLM's training data.

## Features

- **8 tools** covering CVE lookup, bulk scanning, keyword search, product search, recent CVEs, high-severity alerts, database stats, and detailed CVSS breakdowns
- **Multi-source**: NVD, GitHub Advisory, OSV, CIRCL — searched concurrently and deduplicated
- **Smart normalization**: "Node.js", "Spring Boot", "log4j2" all resolve correctly
- **Optional auth**: `GITHUB_TOKEN` and `NVD_API_KEY` for higher rate limits
- **3 transports**: stdio (default), SSE, Streamable HTTP

## Installation

### Prerequisites

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) package manager

### Install

```bash
cd cve-search
uv sync
```

### Development Setup

```bash
uv sync --extra dev
uv run --extra dev pytest
uv run black src/
uv run ruff check src/
```

## Configuration

| Env Var | Default | Description |
|---|---|---|
| `GITHUB_TOKEN` | none | GitHub personal access token. Raises GitHub Advisory API rate limit from 60 to 5000 req/hr. |
| `NVD_API_KEY` | none | NVD API key. Raises rate limit from 5 to 50 req/30s. Get one at [nvd.nist.gov](https://nvd.nist.gov/developers/request-an-api-key). |
| `CVE_SEARCH_TIMEOUT` | `20` | HTTP request timeout in seconds. |
| `CVE_SEARCH_MAX_RESULTS` | `100` | Maximum results returned per tool call. |

## Running

```bash
# stdio (default — for Claude Desktop/IDE)
uv run python main.py

# SSE
uv run python main.py --transport sse --host 127.0.0.1 --port 8000

# Streamable HTTP (MCP spec 2025-06-18+)
uv run python main.py --transport streamable-http --host 127.0.0.1 --port 8000
```

### Claude Desktop Config

```json
{
  "mcpServers": {
    "cve-search": {
      "command": "uv",
      "args": ["--directory", "/path/to/cve-search", "run", "python", "main.py"],
      "env": {
        "GITHUB_TOKEN": "your-token-here",
        "NVD_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Tools

| Tool | Description | Speed |
|---|---|---|
| `search_cve_by_id` | Look up a specific CVE by ID (e.g. CVE-2021-44228) | Fast |
| `bulk_cve_lookup` | Look up up to 20 CVE IDs in one call — ideal for scanning PR dependency lists | Fast |
| `search_vulnerabilities_by_product` | Search by vendor/product name (e.g. vendor="apache", product="struts") | Slow (10-15s) |
| `get_recent_cves` | Get CVEs from the last N days | Fast |
| `check_high_severity_cves` | Get CVSS ≥ 7.0 CVEs from the last N days | Fast |
| `search_by_keyword` | Smart multi-source keyword search (NVD + GitHub Advisory + OSV) | Fast |
| `get_vulnerability_stats` | Database stats: total CVE count, last updated timestamp | Fast |
| `cvss_score_lookup` | Detailed CVSS v3/v4 breakdown for a CVE (base score, vector string, per-metric) | Fast |

## PR Review Workflow

### Scan a list of CVE IDs from a dependency audit

```
bulk_cve_lookup(["CVE-2021-44228", "CVE-2023-44487", "CVE-2024-12345"])
```

### Search for vulnerabilities in a technology being introduced

```
search_by_keyword("spring boot")
```

### Check high-severity CVEs published this week

```
check_high_severity_cves(7)
```

### Get detailed CVSS breakdown for a flagged CVE

```
cvss_score_lookup("CVE-2021-44228")
```

## Project Structure

```
cve-search/
├── src/mcp_server_cve_search/
│   ├── config.py            # Config from env vars
│   ├── server.py            # FastMCP app + transport dispatch
│   ├── tools/               # One module per tool group
│   │   ├── cve_lookup.py    # search_cve_by_id, bulk_cve_lookup
│   │   ├── product_search.py
│   │   ├── recent_cves.py   # get_recent_cves, check_high_severity_cves
│   │   ├── keyword_search.py
│   │   ├── stats.py         # get_vulnerability_stats
│   │   └── cvss.py          # cvss_score_lookup
│   ├── sources/             # One client per API
│   │   ├── circl.py         # CIRCL CVE Search
│   │   ├── nvd.py           # NVD/NIST (optional API key)
│   │   ├── github.py        # GitHub Advisory (optional token)
│   │   └── osv.py           # OSV (Google)
│   └── utils/
│       ├── severity.py      # CVSS score helpers
│       ├── normalization.py # Keyword normalization + tech mappings
│       └── formatting.py    # Summary/alert formatting
├── tests/
├── examples/
├── main.py
├── test_server.py           # Manual live-API integration test
└── pyproject.toml
```

## Data Sources

| Source | URL | Notes |
|---|---|---|
| CIRCL CVE Search | cve.circl.lu | Primary source; no auth required |
| NVD (NIST) | nvd.nist.gov | Richest CVSS data; optional API key |
| GitHub Advisory | github.com/advisories | Optional token for higher rate limits |
| OSV (Google) | osv.dev | Open source vulnerability database |

## License

MIT License