nist-nvd-mcp-server

---

Overview

CVE and CPE data from the NIST National Vulnerability Database. Search and audit vulnerabilities by keyword, severity, CWE, or CISA KEV status, resolve products to CPE names, and track a CVE's revision history.

Tools

Tool	Description
nvd_search_cves	Search CVEs by keyword, severity, CWE, date range, or CISA KEV status.
nvd_get_cve	Fetch one or more CVEs by ID — full CVSS scores, CWE, CPE configs, KEV fields, and references.
nvd_search_cpes	Search the NVD CPE dictionary by product keyword or partial match string.
nvd_audit_cpe	Find all CVEs affecting a specific product version by CPE name or virtual match string.
nvd_get_cve_history	Retrieve the change history for a CVE — score revisions, status transitions, and reference additions.

Resources

Resource	Description
nvd://cve/{cveId}	Full CVE record by ID — same data as nvd_get_cve for a single ID, as a stable URI for injectable context.
skill://nist-nvd-guide/SKILL.md	Product applicability, identifier chains, severity interpretation, and coverage guidance.

CVE resource data is also reachable via nvd_get_cve. The published guide is also available to plugin installs under skills/nist-nvd-guide/SKILL.md.

Capability reference

Oversized read limits clamp by default: 2000 for CVE search, audit, and history; 10000 for CPE search; 100 IDs for batch lookup. Clamped calls report requestedLimit, effectiveLimit, and a notice on both output surfaces. Batch lookup validates every supplied ID and lists normalized, deduplicated IDs beyond the processed prefix in unprocessedIds; missingIds covers queried IDs only. Set NVD_CLAMP_LIMITS=false before startup to restore advertised maxima and reject oversized requests. Zero, negative, and fractional limits remain invalid.

nvd_search_cves _tool

• Full-text keyword search (AND-semantics across words), or exactPhrase: true for an exact-phrase match — requires keyword
• Filters: CVSS severity band (LOW/MEDIUM/HIGH/CRITICAL — CRITICAL requires severityVersion: "v3" or "v4"), CWE ID, CISA KEV status, noRejected (default true)
• Date filters: pubDays/lastModDays convenience shorthands (auto-clamped to 120 days, clamping reported in the enrichment) or explicit ISO 8601 ranges (120-day max span, both ends required); the two forms per axis are mutually exclusive
• Pagination via limit (up to 2000, default 20) and offset
• Always returns brief summaries with a truncated description; call nvd_get_cve for full detail

---

nvd_get_cve _tool

• Batch up to 100 CVE IDs per call
• Full mode (default): CVSS scores across v2.0/v3.0/v3.1/v4.0, CWE weaknesses, CPE configurations, CISA KEV fields, references
• brief: true returns trimmed rows (ID, status, top severity, KEV name, truncated description) — recommended for batches over 10
• includeReferences and includeConfigurations default to true; set either false to omit that field from both output surfaces. allLanguages: true keeps every localized description instead of English-only
• missingIds enrichment field lists any requested IDs NVD didn't return
• Both output surfaces carry every selected reference and CPE configuration; optional SSVC assessments appear when NVD supplies them

---

nvd_search_cpes _tool

• Keyword search (e.g. "apache http server") or a partial CPEv2.3 pattern via cpeMatchString — at least one required
• Returns full CPE name, human-readable title, deprecation status, and superseding CPEs
• Pagination via limit (up to 10,000, default 20) and offset — a vendor-level keyword can match tens of thousands of entries, so page rather than narrowing further
• Use before nvd_audit_cpe to resolve the exact CPE name a product needs

---

nvd_audit_cpe _tool

• Two modes: exact cpeName (NVD auto-applies isVulnerable) or virtualMatchString with optional versionStart/versionEnd bounds (inclusive/exclusive)
• Client-side severityMin filters the fetched page by the highest severity band across all CVSS metrics; the headline still follows the highest numerical score. It can only remove what limit retrieved
• Returns full CVE records (CVSS scores, CWE, CPE configurations, KEV fields, references)
• includeReferences and includeConfigurations default to true; false omits that field from both output surfaces. SSVC assessments remain optional
• Pagination via limit (up to 2000, default 20) and offset — page at a modest limit rather than raising it, since each result is a full record
• auditTarget enrichment field echoes the CPE identifier used, so callers can verify the correct product was queried

---

nvd_get_cve_history _tool

• Returns change events: CVSS revisions, status transitions, reference additions, CPE configuration updates
• order picks the anchor end — newest (default) reads most-recent-first, oldest reads NVD's native order
• Paginated via limit (up to 2000, default 20) and offset, counted from the end order anchors to
• The history endpoint is markedly slower without an API key — set NVD_API_KEY and raise NVD_REQUEST_TIMEOUT_MS

---

nvd://cve/{cveId} _resource

• Full CVE record as application/json — same data as nvd_get_cve for one ID, with references and English-only descriptions
• cveId must match CVE-YYYY-NNNNN; a well-formed but unknown ID throws cve_not_found

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

NVD-specific:

• Request pacer enforces NVD's 5 req/30s (no key) and 50 req/30s (with key) limits with automatic queuing, at a minimum inter-request gap derived from the window and limit
• Retry wraps the pacer rather than sitting inside it — every attempt takes its own turn in the queue, so retries count against the rate budget instead of bursting past it
• A 403's Retry-After holds the whole queue until NVD's window resets; keyless, a 403 fails fast and names NVD_API_KEY rather than spending the 5-request budget on retries that cannot outlast a 30-second window
• Deterministic rejections fail fast instead of consuming retries — NVD answers both a bad parameter and a refused API key with HTTP 404, separated only by a message header, so a refused key surfaces as a config fault naming NVD_API_KEY rather than as a malformed CVE ID
• NVD block pages return a nonretryable blocked-request error; malformed JSON and response envelopes return an invalid-response error with recovery guidance
• Request timeouts and caller cancellation remain active through response-body reads

Agent-friendly output:

• An enrichment block on every response, carried on both structuredContent and the rendered text — total results, returned count, page offset, the filters actually applied, and any date-clamping events, so agents can reason about what was really queried
• missingIds in batch CVE lookups — a per-ID parity check instead of a silent partial result
• CPE echo in audit responses — cpeName or virtualMatchString reflected back so callers can verify the correct product was audited
• Empty-result notices that name the cause — an unmatched query, a severity threshold that emptied the page, an offset past the end of the result set, and a clean audit ("no known vulnerabilities") are told apart rather than all reading as errors or "nothing found"

Getting started

Public Hosted Instance

A public instance is available at https://nist-nvd.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "streamable-http",
      "url": "https://nist-nvd.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/nist-nvd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NVD_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/nist-nvd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NVD_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NVD_API_KEY=your-api-key",
        "ghcr.io/cyanheads/nist-nvd-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NVD_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• Optional: NVD API key — free, raises rate limit from 5 req/30s to 50 req/30s.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/nist-nvd-mcp-server.git

2. Navigate into the directory:

cd nist-nvd-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set NVD_API_KEY if you have one

Configuration

Variable	Description	Default
NVD_API_KEY	NVD API key. Without it, rate limit is 5 req/30s; with it, 50 req/30s. Get one free at nvd.nist.gov/developers/request-an-api-key.	—
NVD_REQUEST_TIMEOUT_MS	Per-request timeout in milliseconds. The history endpoint is slow without an API key — raise to 60000 if using nvd_get_cve_history without a key.	10000
NVD_CLAMP_LIMITS	Clamp oversized reads to 2000 CVEs/events, 10000 CPEs, or 100 CVE IDs. false restores schema maxima and rejection.	true
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for HTTP server.	3010
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

See .env.example for the full list of optional overrides.

Node and Bun load .env from the working directory before server configuration is parsed. Exported variables take precedence. Invalid NVD_CLAMP_LIMITS values fail configuration validation; use true or false.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t nist-nvd-mcp-server .
docker run --rm -e NVD_API_KEY=your-key -p 3010:3010 nist-nvd-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/nist-nvd-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools/resources and inits services.
src/config	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools	Tool definitions (*.tool.ts).
src/mcp-server/resources	Resource definitions (*.resource.ts).
src/services/nvd-http	NVD HTTP client with rate-limit pacing and retry.
src/services/nvd-cve	CVE service — search, fetch-by-ID, CPE audit, change history, normalization.
src/services/nvd-cpe	CPE service — dictionary search and normalization.
src/services/nvd-source	Source service — resolves NVD contributor identifiers to their published names.
tests/	Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.