mcp-nvd

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, default False): If True, 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, default False): If True, requires an exact phrase match.
    • concise (bool, default False): If True, returns shorter CVE records.
    • results (int, default 10): Maximum number of CVE records (1-2000).
  • Returns: List of matching CVEs with total count.

Configuration

1. 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
2. Add the following:

3. Replace /path/to/uvx with the absolute path to the uvx executable. Find the path with which uvx command in a terminal. This ensures that the correct version of uvx is used when starting the server.
4. Restart Claude Desktop to apply the changes.

Development

Setup

1. Prerequisites:
   • Python 3.10 or higher.
   • An NVD API key (request here).
   • uv package manager (installation).
2. Clone the Repository:

3. Set Environment Variables:
   • Create a .env file in the project root:
     NVD_API_KEY=your-api-key
   • Replace your-api-key with your NVD API key.
4. Install Dependencies:

Run with the MCP Inspector

Then open the browser to the URL indicated by the MCP Inspector, typically http://localhost:8077?proxyPort=8078

Switch freely between stdio and sse transport types in the inspector.

Testing with the SSE Client

Run the Server:

• Runs with SSE transport on port 9090 by default.

Run the Client:

Test get_cve:

Test search_cve (default 10 results):

Test search_cve (exact match, 5 results):

Docker Setup

Build

Run

With .env:

With env var:

Custom port:

Verify

Test:

Notes

• Ensure .env has NVD_API_KEY=your-key or 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 the Dockerfile in the parent directory, which sets up the MCP-NVD server with uv and runs it in SSE mode on port 9090.

How to Build the Image

To create the mcp-nvd:test image:

1. Navigate to the project root:
   cd ./mcp-nvd
2. Build the image using the Dockerfile:
   docker build -t mcp-nvd:test .
   • This builds the image with all dependencies from pyproject.toml and the mcp_nvd/ module, setting the default command to run the server.

Running the Service

From the tests/ directory:

• Access: The server runs at http://localhost:9090.
• Stop: docker-compose down.
• Environment: Ensure NVD_API_KEY is in ../.env or use docker-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:

1. Start the Service: Ensure the mcp-nvd service is running via docker-compose up.
2. 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.py is copied into the image at /app/tests/. If not, modify the Dockerfile to include:
     COPY tests/ ./tests/
     Then rebuild the image with docker build -t mcp-nvd:test . from the root.
3. Alternative: Run tests locally against the containerized service:
   cd tests python test_tools.py
   • This tests against http://localhost:9090 while the service runs.

Key Details

• Port: 9090 is exposed for SSE access.
• Logs: Stored in a log-data volume (optional).
• Image: Must be built once and tagged as mcp-nvd:test before running docker-compose.

Credits to @sidharthrajaram for its working pattern for SSE-based MCP clients and servers: https://github.com/sidharthrajaram/mcp-sse