NVD Database MCP Server
A Model Context Protocol server implementation to query the NIST National Vulnerability Database (NVD) via its API. https://nvd.nist.gov/
As a prerequisite an NVD API key is required. (Request here).
Status
Works with Claude Desktop app and other MCP compliant hosts and clients using both the stdio and sse transports.
Features
- Query specific CVEs by ID with detailed vulnerability data.
- Search the NVD database by keyword with customizable result options.
- Supports Server-Sent Events (SSE) transport for real-time communication.
- Compatible with MCP-compliant clients like Claude Desktop.
Tools
The server implements the following tools to query the NVD Database:
-
get_cve:- Description: Retrieves a CVE record by its ID.
- Parameters:
cve_id(str): The CVE ID (e.g.,CVE-2019-1010218).concise(bool, defaultFalse): IfTrue, returns a shorter format.
- Returns: Detailed CVE info including scores, weaknesses, and references.
-
search_cve:- Description: Searches the NVD database by keyword.
- Parameters:
keyword(str): Search term (e.g.,Red Hat).exact_match(bool, defaultFalse): IfTrue, requires an exact phrase match.concise(bool, defaultFalse): IfTrue, returns shorter CVE records.results(int, default10): Maximum number of CVE records (1-2000).
- Returns: List of matching CVEs with total count.
Configuration
-
Create or edit the Claude Desktop configuration file located at:
- On macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - On Windows:
%APPDATA%/Claude/claude_desktop_config.json
- On macOS:
-
Add the following:
{
"mcpServers": {
"mcp-nvd": {
"command": "/path/to/uv",
"args": ["run", "mcp-nvd"],
"env": {
"NVD_API_KEY": "your-api-key"
}
}
}
}
-
Replace
/path/to/uvwith the absolute path to theuvexecutable. Find the path withwhich uvcommand in a terminal. This ensures that the correct version ofuvis used when starting the server. -
Restart Claude Desktop to apply the changes.
Development
Setup
-
Prerequisites:
- Python 3.10 or higher.
- An NVD API key (request here).
uvpackage manager (installation).
-
Clone the Repository:
git clone https://github.com/marcoeg/mcp-nvd
cd mcp-nvd
-
Set Environment Variables:
- Create a
.envfile in the project root:NVD_API_KEY=your-api-key - Replace
your-api-keywith your NVD API key.
- Create a
-
Install Dependencies:
uv sync
uv pip install -e .
Run with the MCP Inspector
cd /path/to/the/repo
source .env
npx @modelcontextprotocol/inspector uv \
--directory /path/to/repo/mcp-nvd run mcp-nvd
Then open the browser to the URL indicated by the MCP Inspector, typically http://localhost:8077?proxyPort=8078
Switch freely between
stdioandssetransport types in the inspector.
Testing with the SSE Client
Run the Server:
cd /path/to/the/repo
source .env
uv run mcp-nvd --transport sse --port 9090
- Runs with SSE transport on port
9090by default.
Run the Client:
Test get_cve:
uv run client.py http://localhost:9090/sse CVE-2019-1010218
Test search_cve (default 10 results):
uv run client.py http://localhost:9090/sse "search:Red Hat"
Test search_cve (exact match, 5 results):
uv run client.py http://localhost:9090/sse "search:Microsoft Windows:exact:5"
Docker Setup
Build
docker build -t mcp-nvd:latest .
Run
With .env:
docker run -d -p 9090:9090 -v /path/to/.env:/app/.env mcp-nvd:latest
With env var:
docker run -d -p 9090:9090 -e NVD_API_KEY="your-key" mcp-nvd:latest
Custom port:
docker run -d -p 8080:8080 -v /path/to/.env:/app/.env mcp-nvd:latest uv run mcp-nvd --transport sse --port 8080 --host 0.0.0.0
Verify
docker logs <container_id>
# Expect: INFO: Uvicorn running on http://0.0.0.0:9090
Test:
uv run client.py http://localhost:9090/sse CVE-2019-1010218
Notes
- Ensure
.envhasNVD_API_KEY=your-keyor use-e. - Default port:
9090.
Here’s the summary formatted as Markdown comments within a code block, suitable for inclusion in a file like docker-compose.yaml or README.md:
Using Docker Compose for Testing
This docker-compose.yaml, located in the tests/ directory, defines a service for testing the MCP-NVD server using a pre-built Docker image. It’s designed for a testing use case, similar to a standalone service like clickhouse, and assumes the image is built beforehand rather than rebuilt each time.
Assumptions
- Pre-built Image: The service uses a pre-built image tagged as
mcp-nvd:test, available locally or in a registry. The image is based on theDockerfilein the parent directory, which sets up the MCP-NVD server withuvand runs it in SSE mode on port 9090.
How to Build the Image
To create the mcp-nvd:test image:
- Navigate to the project root:
cd ./mcp-nvd
- Build the image using the Dockerfile:
docker build -t mcp-nvd:test .
- This builds the image with all dependencies from
pyproject.tomland themcp_nvd/module, setting the default command to run the server.
- This builds the image with all dependencies from
Running the Service
From the tests/ directory:
cd tests
docker-compose up
- Access: The server runs at
http://localhost:9090. - Stop:
docker-compose down. - Environment: Ensure
NVD_API_KEYis in../.envor usedocker-compose --env-file ../.env up.
Running test_tools.py in the Docker Compose Scenario
To run the unit tests (test_tools.py) within the Docker environment:
- Start the Service: Ensure the
mcp-nvdservice is running viadocker-compose up. - Exec into the Container:
- Identify the container name (e.g.,
mcp-nvd-mcp-nvd-1) with:docker ps - Run the tests inside the container:
docker exec -it mcp-nvd-mcp-nvd-1 python /app/tests/test_tools.py
- Note: Assumes
test_tools.pyis copied into the image at/app/tests/. If not, modify the Dockerfile to include:COPY tests/ ./tests/
Then rebuild the image withdocker build -t mcp-nvd:test .from the root.
- Identify the container name (e.g.,
- Alternative: Run tests locally against the containerized service:
cd tests python test_tools.py
- This tests against
http://localhost:9090while the service runs.
- This tests against
Key Details
- Port: 9090 is exposed for SSE access.
- Logs: Stored in a
log-datavolume (optional). - Image: Must be built once and tagged as
mcp-nvd:testbefore runningdocker-compose.
Credits to @sidharthrajaram for its working pattern for SSE-based MCP clients and servers: https://github.com/sidharthrajaram/mcp-sse
Metadata
Release files for mcp-nvd 0.0.1
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 |
|---|---|---|---|---|
| mcp_nvd-0.0.1.tar.gz | 25.6 kB | Without provenance | Details for mcp_nvd-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_nvd-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for mcp_nvd-0.0.1-py3-none-any.whl |
Total release size: 36.3 kB
Release files / mcp_nvd-0.0.1.tar.gz
| Download URL | mcp_nvd-0.0.1.tar.gz |
|---|---|
| Size | 25.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
999b42f85221546afde5cdae4d7200f09d08eb244ce9c27c313fca176275750a
|
|
BLAKE2b-256 checksum How to use checksums |
d71e07f3aad16ff3f899b012d43600d2558615e9b72489d42701a3b6b59c0dbc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.2
|
Release files / mcp_nvd-0.0.1-py3-none-any.whl
| Download URL | mcp_nvd-0.0.1-py3-none-any.whl |
|---|---|
| Size | 10.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
76038251498a92371c4b3d73db206b78af31f576da811b45c3f9b59272f10d00
|
|
BLAKE2b-256 checksum How to use checksums |
cd1c3bda45f54afe63b5399527ef3da0100ac2fd1cebcb4a63e5e9593d242d52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.2
|
Security for mcp-nvd 0.0.1
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.