.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/nist-nvd-mcp-server</h1> <p><b>Search and audit CVEs by keyword, severity, CWE, CISA KEV status, and CPE via the NIST National Vulnerability Database. STDIO or Streamable HTTP.</b> <div>5 Tools • 2 Resources</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

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

</div>

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

Resources

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

1. Navigate into the directory:

cd nist-nvd-mcp-server

1. Install dependencies:

bun install

1. 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.

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

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.