Metadata-Version: 2.4
Name: nvd-cve-mcp-server
Version: 0.1.2
Summary: MCP stdio server for querying CVE data from the NVD API v2.0
Project-URL: Homepage, https://github.com/millsks/nvd-cve-mcp-server
Project-URL: Issues, https://github.com/millsks/nvd-cve-mcp-server/issues
Project-URL: Documentation, https://github.com/millsks/nvd-cve-mcp-server
Author: millsks
License: MIT License
        
        Copyright (c) 2026 Kevin Mills
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cve,mcp,nvd,security,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.9.0
Description-Content-Type: text/markdown

# 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

```text
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`

```bash
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:

```bash
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:

```bash
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.

```bash
pixi run build-conda
```

### Changelog generation

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

```bash
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

```bash
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**:

```python
mcp.run(transport="stdio")
```

## Example MCP Client Configuration (Claude Desktop style)

Adjust Python path/environment for your machine:

```json
{
  "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:**
```json
{ "cve_id": "CVE-2024-3094" }
```

### 2) `search_cve_by_keyword`

Search by keyword with no date filter:

**Input:**
```json
{ "keyword": "openssl", "limit": 5 }
```

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

**Input:**
```json
{ "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:**
```json
{ "limit": 10, "days_back": 7 }
```

### 4) `search_by_severity`

**Input:**
```json
{ "severity": "HIGH", "limit": 10 }
```

## Response Shape

Each tool returns a normalized structure like:

```json
{
  "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:

```json
{
  "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 |
