nist-nvd-mcp-server

Public Hosted Server: https://nist-nvd.caseyjhand.com/mcp

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 from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Resources

All resource data is also reachable via tools.

Related MCP server: Cybersecurity MCP Server

Capability reference

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: false strips the references array; allLanguages: true renders every localized description instead of English-only

• missingIds enrichment field lists any requested IDs NVD didn't return

• Rendered text caps references at 15 per record, with a … N more trailer

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 filter drops low-signal entries from the fetched page — it can only remove what limit already retrieved

• Returns full CVE records (CVSS scores, CWE, CPE configurations, KEV fields, references)

• 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

• HTML-response guard catches NVD rate-limit pages served as HTML instead of a 403

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

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

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

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.