nvd-cve-mcp-server 0.1.0

MCP stdio server for querying CVE data from the NVD API v2.0

NVD CVE MCP Server (Python, stdio)

A Model Context Protocol (MCP) server that exposes CVE search tools backed by the NVD API v2.0.

Features

• search_cve_by_id — look up an exact CVE ID (e.g. CVE-2024-1234)
• search_cve_by_keyword — search by product name/keyword, with optional days_back date filter
• get_recent_cves — get newly published CVEs from a configurable time window (default: 7 days)
• search_by_severity — filter by severity: CRITICAL, HIGH, MEDIUM, LOW
• NVD API rate limiting + automatic retry with exponential backoff (handles 429, 5xx errors)
• Respects Retry-After response headers; up to 3 retries per request
• NVD API date range limit enforced: days_back is validated against the 120-day maximum
• stdio transport (recommended for Claude Desktop and most MCP clients)

Data Source

• NVD Vulnerability API v2.0:
  • https://nvd.nist.gov/developers/vulnerabilities
  • Endpoint used: https://services.nvd.nist.gov/rest/json/cves/2.0

Project Structure

nvd_cve_mcp_server/
├── pixi.toml
├── pyproject.toml
├── README.md
└── src/nvd_cve_mcp_server/
    ├── __init__.py
    ├── nvd_client.py
    └── server.py

Setup

Option 1: pixi (recommended)

Supported platforms: linux-64, linux-aarch64, osx-arm64, osx-64, win-64

cd nvd-cve-mcp-server
pixi install
pixi run run-mcp-server

Development workflow (pixi tasks)

The project uses pixi tasks for all quality and packaging workflows:

pixi run lint          # ruff lint
pixi run format        # ruff formatter
pixi run format-check  # verify formatting only
pixi run typecheck     # mypy (strict)
pixi run test          # pytest
pixi run check         # lint + format-check + typecheck + test

Build and release artifacts

• PyPI artifacts (wheel + sdist) are built with Hatch:

pixi run build-pypi

• Conda package is built from a v1 recipe (recipe/recipe.yaml) aligned with conda-forge/feedstock workflows. The recipe source is expected to be a version tag tarball (v<version>) with a pinned SHA256.

pixi run build-conda

Changelog generation

git-cliff is configured in pyproject.toml and generates CHANGELOG.md from Conventional Commit history.

pixi run changelog

Conventional Commits

Use commit messages that follow: type(scope): description

Common types:

• feat: new functionality
• fix: bug fix
• docs: documentation changes
• refactor: internal refactors
• test: tests
• build: packaging/build tooling
• ci: CI/CD changes
• chore: maintenance

Examples:

• feat(server): add severity filter tool
• fix(nvd): handle retry-after parsing
• build(release): add hatch pypi build task

History rewrite note: if commit history is rewritten to conform to Conventional Commits, coordinate with collaborators and force-push carefully.

Option 2: pip / venv

cd nvd-cve-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .
python -m nvd_cve_mcp_server.server

Configuration

Environment variables:

• NVD_API_KEY (optional, recommended for higher NVD rate limits)
• NVD_RATE_LIMIT_REQUESTS (optional)
• NVD_RATE_LIMIT_WINDOW_SECONDS (optional)

Defaults used by server:

• Without API key: 5 requests / 30 seconds
• With API key: 50 requests / 30 seconds

MCP Transport

The server uses stdio transport:

mcp.run(transport="stdio")

Example MCP Client Configuration (Claude Desktop style)

Adjust Python path/environment for your machine:

{
  "mcpServers": {
    "cve": {
      "command": "python",
      "args": ["-m", "nvd_cve_mcp_server.server"],
      "cwd": "/path/to/nvd-cve-mcp-server",
      "env": {
        "NVD_API_KEY": "your_api_key_here"
      }
    }
  }
}

Tool Usage Examples

1) search_cve_by_id

Input:

{ "cve_id": "CVE-2024-3094" }

2) search_cve_by_keyword

Search by keyword with no date filter:

Input:

{ "keyword": "openssl", "limit": 5 }

Search by keyword limited to the last 30 days (days_back max is 120):

Input:

{ "keyword": "openssl", "limit": 5, "days_back": 30 }

3) get_recent_cves

Defaults to the last 7 days. Accepts any value from 1–120 for days_back:

Input:

{ "limit": 10, "days_back": 7 }

4) search_by_severity

Input:

{ "severity": "HIGH", "limit": 10 }

Response Shape

Each tool returns a normalized structure like:

{
  "success": true,
  "total_results": 123,
  "returned_results": 10,
  "cves": [
    {
      "id": "CVE-2024-0001",
      "published": "2024-01-01T00:00:00.000",
      "last_modified": "2024-01-02T00:00:00.000",
      "description": "...",
      "severity": "HIGH",
      "base_score": 7.5,
      "vector": "CVSS:3.1/...",
      "cwes": ["CWE-79"],
      "references": ["https://..."]
    }
  ]
}

Error case:

{
  "success": false,
  "error": "NVD API request failed ..."
}

Error Handling & Retry Behavior

The NVDClient automatically retries transient failures up to 3 times using exponential backoff with jitter:

Condition	Behavior
HTTP 429 / 5xx	Retry with backoff; honour Retry-After header if present
Timeout	Retry with backoff
Network error	Retry with backoff
Invalid date range (days_back > 120)	Immediate error — no retry
Invalid severity value	Immediate error — no retry