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 optionaldays_backdate filterget_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-Afterresponse headers; up to 3 retries per request - NVD API date range limit enforced:
days_backis 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 functionalityfix: bug fixdocs: documentation changesrefactor: internal refactorstest: testsbuild: packaging/build toolingci: CI/CD changeschore: maintenance
Examples:
feat(server): add severity filter toolfix(nvd): handle retry-after parsingbuild(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:
5requests /30seconds - With API key:
50requests /30seconds
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 |
Metadata
Release files for nvd-cve-mcp-server 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nvd_cve_mcp_server-0.1.2.tar.gz | 14.7 kB | Without provenance | Details for nvd_cve_mcp_server-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nvd_cve_mcp_server-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for nvd_cve_mcp_server-0.1.2-py3-none-any.whl |
Total release size: 24.7 kB
Release files / nvd_cve_mcp_server-0.1.2.tar.gz
| Download URL | nvd_cve_mcp_server-0.1.2.tar.gz |
|---|---|
| Size | 14.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e5612d30d251e1755cc3d7490a16e29ce9f7180be4392246d60df8927e295700
|
|
BLAKE2b-256 checksum How to use checksums |
8693fcd14722965ea803b2e1f1f97ad4d57602591fedeebf1234de5d834fa86a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / nvd_cve_mcp_server-0.1.2-py3-none-any.whl
| Download URL | nvd_cve_mcp_server-0.1.2-py3-none-any.whl |
|---|---|
| Size | 10.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
422d59f33c013a6f07bbda5664febe04b4d404e09f3beca27ca239c518118355
|
|
BLAKE2b-256 checksum How to use checksums |
65ad5309395478afaf2b71e5d14237a8344dc4f7d0d6361dd75428882d3cea94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for nvd-cve-mcp-server 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.