NVD Server

NVD API Integration Tests

nvd-mcp-server MCP server

A Model Context Protocol (MCP) server that lets AI assistants like Claude, Cursor, and Gemini search the National Vulnerability Database (NVD) for security vulnerabilities and their change history — in plain English, no API knowledge required.

Ask your AI assistant things like:

• "Find critical CVEs published this month"
• "What vulnerabilities affect OpenSSL 3.0.0?"
• "Look up Log4Shell"
• "Show me the full change history for CVE-2021-44228"
• "Which Log4Shell changes came from NVD analysts?"

---

How it works

sequenceDiagram
    actor User
    participant Agent as AI Assistant<br/>(Claude / Cursor / Gemini)
    participant MCP as NVD MCP Server
    participant NVD as NVD API<br/>(nvd.nist.gov)

    User->>Agent: "Find critical CVEs in Apache Log4j"
    Agent->>MCP: search_cves(keyword_search="Apache Log4j",<br/>cvss_v3_severity="CRITICAL")
    MCP->>NVD: GET /rest/json/cves/2.0<br/>?keywordSearch=Apache+Log4j<br/>&cvssV3Severity=CRITICAL<br/>&apiKey=...
    NVD-->>MCP: Raw vulnerability JSON
    MCP->>MCP: Validate & condense response
    MCP-->>Agent: id, description, CVSS score,<br/>CWEs, references, KEV status
    Agent-->>User: Formatted summary of matching CVEs

The server sits between your AI assistant and the NVD API. It:

1. Receives natural-language-driven tool calls from the AI
2. Translates them into authenticated NVD API requests
3. Validates the raw response against strict data models
4. Returns a clean, condensed result the AI can reason about

---

Tools

search_cves

Search the NVD CVE database with any combination of filters. Returns up to 10 CVEs per page, each with id, published date, status, description, CVSS score, CWEs, top 5 references, and CISA KEV data.

search_cve_history

Search the NVD CVE Change History API to see every modification made to a CVE record — description updates, CVSS score changes, CWE remaps, CPE configuration changes, KEV additions, and more. Returns a paginated list of change events with full before/after details.

---

Prerequisites

• Python 3.11+
• uv — fast Python package manager
• An NVD API key (free, takes ~1 hour to receive)

---

Step 1 — Get an NVD API key

The NVD API is free and open, but an API key increases your rate limit from 5 requests/30 seconds to 50 requests/30 seconds.

1. Go to https://nvd.nist.gov/developers/request-an-api-key
2. Enter your email address and submit the form
3. Check your email — you'll receive your key within an hour
4. Copy the key, you'll need it in the next step

---

Step 2 — Install the server

git clone https://github.com/Alig1493/nvd-mcp-server.git
cd nvd-mcp-server
uv sync

---

Step 3 — Configure your API key

Create a .env file in the project root:

NVD_API_KEY=your-api-key-here

That's the only required setting. The NVD API URLs are pre-configured.

---

Step 4 — Connect to your AI assistant

The server supports two transports: local stdio (spawn a process) and remote Streamable HTTP (connect over a network).

Option A: Local Process Setup (stdio)

Great for single-user local workflows where your assistant spawns the server directly.

Claude Desktop

Open your Claude Desktop config file:

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

Add the following inside the "mcpServers" object:

{
  "mcpServers": {
    "nvd-mcp-server": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/nvd-mcp-server",
        "run", "nvd-mcp-server",
        "--transport", "stdio"
      ],
      "env": {
        "NVD_API_KEY": "your-api-key-here"
      }
    }
  }
}

Replace /absolute/path/to/nvd-mcp-server with your local repository root. Restart Claude Desktop.

Claude Code (CLI)

claude mcp add nvd-mcp-server \
  --command uv \
  --args "--directory /absolute/path/to/nvd-mcp-server run nvd-mcp-server --transport stdio" \
  --env NVD_API_KEY=your-api-key-here

Cursor

Open Cursor → Settings → MCP, then add:

• Name: nvd-mcp-server
• Type: command
• Command: uv --directory /absolute/path/to/nvd-mcp-server run nvd-mcp-server --transport stdio

---

Option B: Cloud or Container Setup (Streamable HTTP)

Perfect for shared deployments or clients that connect over a network.

Start the server:

docker compose up --build -d

Connect your client using the /mcp endpoint:

{
  "mcpServers": {
    "nvd-mcp-server": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

The NVD_API_KEY is read from your .env file automatically by Docker Compose.

Custom port:

docker run -d -p 9090:8000 --env-file .env nvd-mcp-server-app \
  nvd-mcp-server --transport http --host 0.0.0.0 --port 9090

---

Example prompts

Look up a specific CVE

"What is CVE-2021-44228?"

CVE-2021-44228 — Log4Shell
Published: 2021-12-10 | Status: Analyzed
CVSS: 10.0 CRITICAL (CVSSv3.1) | AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H

Apache Log4j2 2.0-beta9 through 2.15.0 JNDI features do not protect against
attacker-controlled LDAP endpoints. An attacker who can control log messages
can execute arbitrary code loaded from a remote server.

CWEs: CWE-20, CWE-400, CWE-502, CWE-917
CISA KEV: Added 2021-12-10 · Due 2021-12-24

---

Find vulnerabilities for a product

"What are the critical vulnerabilities affecting OpenSSL 3.0.0?"

---

Search by keyword

"Find recent CVEs related to remote code execution in Windows"

"Show me SQL injection vulnerabilities from the last 6 months"

---

Filter by severity

"List high and critical CVEs published in January 2025"

"Find all CVEs in CISA's Known Exploited Vulnerabilities catalog from Q1 2023"

---

Track CVE changes over time

"Show me the change history for CVE-2021-44228"

"What Initial Analysis events happened in January 2024?"

"Show me all CVE CISA KEV updates from last month"

---

Paginate through results

"Show me the next page of results"

Every response includes a pagination_hint telling the assistant exactly how many results remain and how to fetch the next page.

---

Available filters (reference)

search_cves

Filter	What it does	Example value
cve_id	Look up a specific CVE	CVE-2021-44228
keyword_search	Search descriptions	"buffer overflow"
keyword_exact_match	Exact phrase match	true
cvss_v3_severity	Filter by CVSSv3 severity	CRITICAL, HIGH, MEDIUM, LOW
cvss_v2_severity	Filter by CVSSv2 severity	HIGH, MEDIUM, LOW
cvss_v3_metrics	Match a CVSSv3 vector string	AV:N/AC:L/PR:N/UI:N
cwe_id	Filter by weakness type	CWE-79, CWE-89
cpe_name	Filter by affected product	cpe:2.3:a:openssl:openssl:3.0.0:*:*:*:*:*:*:*
is_vulnerable	Only confirmed vulnerable configs	true (requires cpe_name)
virtual_match_string	Broad product match	cpe:2.3:o:linux:linux_kernel
pub_start_date / pub_end_date	Published date range	2024-01-01T00:00:00.000
last_mod_start_date / last_mod_end_date	Last modified date range	2025-01-01T00:00:00.000
kev_start_date / kev_end_date	CISA KEV addition date range	2023-01-01T00:00:00.000
has_kev	Only KEV catalog CVEs	true
no_rejected	Exclude rejected CVEs	true
cve_tag	Filter by tag	disputed, unsupported-when-assigned
start_index	Pagination offset	10, 20, ...

search_cve_history

Filter	What it does	Example value
cve_id	Full history for a specific CVE	CVE-2021-44228
event_name	Filter by change event type	Initial Analysis, CVE Rejected, CVE CISA KEV Update
change_start_date / change_end_date	Date range of changes (max 120 days)	2024-01-01T00:00:00.000
results_per_page	Results per page (max 5,000)	10
start_index	Pagination offset	10, 20, ...

Supported event names: CVE Received, Initial Analysis, Reanalysis, CVE Modified, Modified Analysis, CVE Translated, Vendor Comment, CVE Source Update, CPE Deprecation Remap, CWE Remap, Reference Tag Update, CVE Rejected, CVE Unrejected, CVE CISA KEV Update, Data Remediation, CVE Status Change

---

Notes

CVSSv2: NVD stopped generating CVSSv2 data on 2022-07-13. cvss_v2_severity and cvss_v2_metrics filters only match pre-2022 CVEs.

Date ranges: The maximum allowable range for any date filter is 120 consecutive days. Requests spanning a longer period will be rejected by the NVD API.

Rate limits: Without an API key you are limited to 5 requests per 30 seconds. Get a free key at https://nvd.nist.gov/developers/request-an-api-key.

---

Configuration options

Variable	Default	Description
NVD_API_KEY	(required)	Your NVD API key
NVD_CVE_URL	https://services.nvd.nist.gov/rest/json/cves/2.0	NVD CVE endpoint
NVD_CVE_HISTORY_URL	https://services.nvd.nist.gov/rest/json/cvehistory/2.0	NVD history endpoint
TOTAL_TIMEOUT	60.0	Per-request HTTP timeout in seconds
RETRY_MAX_DURATION	120	Total retry budget in seconds

---

Running the tests

End-to-end stdio tests (covers all search_cves and search_cve_history parameters):

uv run src/scripts/test_stdio_connection.py

HTTP smoke test (requires the Docker container to be running):

uv run src/scripts/test_http_connection.py
uv run src/scripts/test_http_connection.py --url http://localhost:9090/mcp

To run the tests in CI, add NVD_API_KEY as a repository secret in GitHub → Settings → Secrets → Actions.

---

Troubleshooting

The tool doesn't appear in my AI assistant Restart the application after editing the config file. Check that the path to the repo is absolute (not ~ or relative).

NVD_API_KEY validation error on startup The server requires an API key. Make sure NVD_API_KEY is set either in .env or in the "env" block of your MCP config.

Requests timing out The NVD API can be slow for broad queries. Try narrowing your search with additional filters. You can also increase the timeout: TOTAL_TIMEOUT=120.

Rate limit errors (HTTP 403) Without an API key you are limited to 5 requests per 30 seconds. Get a free key at https://nvd.nist.gov/developers/request-an-api-key.