CVE MCP Server (Prototype)

A local, containerized Model Context Protocol (MCP) server that provides conversational access to a CVE (Common Vulnerabilities and Exposures) database.

PROTOTYPE: This is a project demonstrating MCP server implementation. It is functional but not production-ready.

Overview

This project enables natural-language queries against a local CVE database using any MCP-compatible client. All data is stored locally for privacy and can be refreshed from public CVE sources.

Features

Fully Local: All data stored on your machine (stdio transport only)
Refreshable: Update CVE data from GitHub CVE database
Containerized: Runs in Docker for portability
MCP Compatible: Works with MCP Inspector and other MCP clients
Three Tools:
- get_cve_details: Retrieve detailed CVE information by ID
- search_cves: Search vulnerabilities by keyword
- get_statistics: View database metadata and counts

Prerequisites

Docker (with docker compose support)
Python 3.11+ (for local development)
Node.js 18+ (for MCP Inspector)

Quick Start with Docker

1. Clone the Repository

git clone https://github.com/yourusername/cve-mcp-server.git
cd cve-mcp-server

2. Build Docker Image

docker build -t cve-mcp-server .

3. Load CVE Data

./scripts/docker_load_data.sh

This downloads ~100 recent CVEs from GitHub (takes 1-2 minutes).

4. Start Container

docker compose up -d

Verify it's running:

docker ps

5. Test with MCP Inspector

npx @modelcontextprotocol/inspector

In the Inspector UI, configure:

Command: docker
Arguments: exec -i cve-mcp-server python -m src.mcp_server
Environment Variables (expand section):
- Name: PYTHONPATH
- Value: /app

Click Connect and test the tools!

Local Development (Without Docker)

1. Setup Python Environment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Load CVE Data

python -m src.data_ingestion.loader --year 2024 --limit 100

3. Run MCP Server

python -m src.mcp_server

The server will wait for MCP client connections via stdio.

4. Test Locally with MCP Inspector

In a new terminal, start MCP Inspector:

cd ~/workspace/projects/cve-mcp-server
source venv/bin/activate
npx @modelcontextprotocol/inspector

Configure connection:

Command: python
Arguments: -m src.mcp_server
Environment Variables:
- Name: PYTHONPATH
- Value: /home/yourusername/workspace/projects/cve-mcp-server

Click Connect and test!

5. Run Unit Tests

# Test database operations
python tests/test_database.py

# Test MCP tools directly
python tests/test_tools.py

Available MCP Tools

get_cve_details

Get detailed information about a specific CVE.

Parameters:

cve_id (string, required): CVE identifier (e.g., "CVE-2024-0001")

Example Request:

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

Example Response:

{
  "cve_id": "CVE-2024-0001",
  "description": "A critical vulnerability in Apache HTTP Server...",
  "severity": "CRITICAL",
  "cvss_score": 9.8,
  "published_date": "2024-01-15",
  "modified_date": "2024-01-20",
  "references": ["https://..."]
}

search_cves

Search for CVEs by keyword in descriptions.

Parameters:

keyword (string, required): Search term
limit (integer, optional): Max results (default: 10, max: 50)

Example Request:

{
  "keyword": "remote code execution",
  "limit": 10
}

Example Response:

{
  "query": "remote code execution",
  "count": 5,
  "results": [
    {
      "cve_id": "CVE-2024-0015",
      "severity": "HIGH",
      "cvss_score": 8.5,
      "description": "Remote code execution...",
      "published_date": "2024-01-10"
    }
  ]
}

get_statistics

Get database statistics and metadata.

Parameters: None

Example Response:

{
  "database_info": {
    "total_cves": 95,
    "date_range": {
      "oldest": "2024-01-05",
      "newest": "2024-02-15"
    },
    "last_update": "2025-01-18T14:32:00.123456"
  }
}

Data Management

Load More CVE Data (Docker)

# Load 500 CVEs from 2024
docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 500

# Load from different year
docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2023 --limit 200

Load More CVE Data (Local)

python -m src.data_ingestion.loader --year 2024 --limit 500

Check Database Status

# Using Docker
docker exec cve-mcp-server python -c "
import sys
sys.path.insert(0, '/app')
from src.database.db import init_db, get_stats
print(get_stats(init_db()))
"

# Using local Python
python -c "
import sys
from pathlib import Path
sys.path.insert(0, str(Path.cwd() / 'src'))
from database.db import init_db, get_stats
print(get_stats(init_db()))
"

Project Structure

cve-mcp-server/
├── src/
│   ├── mcp_server/           # MCP server implementation
│   │   ├── server.py         # Server and tool definitions
│   │   ├── tools.py          # Tool implementation logic
│   │   └── __main__.py       # Entry point
│   ├── database/             # Database layer
│   │   └── db.py             # SQLite schema and queries
│   └── data_ingestion/       # CVE data pipeline
│       └── loader.py         # GitHub CVE fetcher/parser
├── data/                     # SQLite database (Docker volume)
├── tests/                    # Unit tests
│   ├── test_database.py      # Database operation tests
│   └── test_tools.py         # Tool logic tests
├── scripts/                  # Utility scripts
│   └── docker_load_data.sh   # Load CVE data into container
├── Dockerfile                # Container image definition
├── docker-compose.yml        # Container orchestration
├── requirements.txt          # Python dependencies
└── README.md                 # This file

Technologies Used

Python 3.11: Core language
MCP SDK: Model Context Protocol implementation
SQLite: Local database with full-text search capability
Docker: Containerization and deployment
GitHub CVE Database: Data source (CVEProject/cvelistV5)

Testing

Manual Testing with MCP Inspector

MCP Inspector provides an interactive UI to test all tools:

Start the server (Docker or local)
Run npx @modelcontextprotocol/inspector
Configure connection (see Quick Start sections above)
Test each tool with various inputs

Automated Testing

# Database operations
python tests/test_database.py

# Tool implementations
python tests/test_tools.py

Troubleshooting

Docker Issues

Container won't start:

docker logs cve-mcp-server
docker compose down
docker compose up -d

No CVE data loaded:

./scripts/docker_load_data.sh

Rebuild after code changes:

docker compose down
docker build -t cve-mcp-server .
docker compose up -d

MCP Inspector Connection Issues

Connection fails:

Verify container is running: docker ps
Check exact command: docker exec -i cve-mcp-server python -m src.mcp_server
Ensure container name matches: cve-mcp-server

Tools not appearing:

Check server logs for import errors
Verify PYTHONPATH is set correctly

Local Development Issues

Import errors:

Ensure virtual environment is activated
Check PYTHONPATH includes project root
Verify all dependencies installed: pip install -r requirements.txt

Database not found:

Check data/cve.db exists
Run data loader: python -m src.data_ingestion.loader

Limitations (Prototype Status)

Local only: Uses stdio transport, not accessible over network
Basic search: Simple keyword matching, no advanced filtering
Small dataset: Prototype loads ~100-500 CVEs (full dataset is 240K+)
No authentication: Local use only, no access controls
Manual refresh: CVE data updates require manual script execution

TODO / Future Enhancements

High Priority

Network Access: Implement SSE transport to expose tools over HTTP/network
Full-Text Search: Add SQLite FTS5 for better search performance
Complete Dataset: Load and index all 240K+ CVEs
Advanced Filtering: Support filtering by CVSS score, severity, date ranges, affected products

Medium Priority

Automated Refresh: Scheduled cron job to update CVE data daily/weekly
Example Client: Build Streamlit + LM Studio/Ollama conversational UI
REST API Wrapper: HTTP API for non-MCP clients
CVE Monitoring: Track specific CVEs and alert on updates

Low Priority

Export Functionality: Generate PDF/CSV reports
Statistics Dashboard: Visualize CVE trends over time
Multi-user Support: Authentication and user isolation
Performance Optimization: Caching, query optimization for large datasets

Contributing

This is a prototype project.

Contributions welcome:

Bug fixes
Documentation improvements
Feature implementations from TODO list
Additional test coverage

License

MIT License - See LICENSE file for details

Acknowledgments

CVE data sourced from CVEProject/cvelistV5
Built with Anthropic MCP SDK

Note: This is a prototype project. For production use, consider implementing the TODO items, especially network security, authentication, and comprehensive error handling.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt
test_setup.py		test_setup.py

License

davidculver/cve-mcp-server

Folders and files

Latest commit

History

Repository files navigation

CVE MCP Server (Prototype)

Overview

Features

Prerequisites

Quick Start with Docker

1. Clone the Repository

2. Build Docker Image

3. Load CVE Data

4. Start Container

5. Test with MCP Inspector

Local Development (Without Docker)

1. Setup Python Environment

2. Load CVE Data

3. Run MCP Server

4. Test Locally with MCP Inspector

5. Run Unit Tests

Available MCP Tools

get_cve_details

search_cves

get_statistics

Data Management

Load More CVE Data (Docker)

Load More CVE Data (Local)

Check Database Status

Project Structure

Technologies Used

Testing

Manual Testing with MCP Inspector

Automated Testing

Troubleshooting

Docker Issues

MCP Inspector Connection Issues

Local Development Issues

Limitations (Prototype Status)

TODO / Future Enhancements

High Priority

Medium Priority

Low Priority

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages