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 on your machine, stdio transport only

• Refreshable CVE data from GitHub database

• Runs in Docker

• Works with MCP Inspector and other MCP clients

• Three tools: get_cve_details, search_cves, get_statistics

Prerequisites

• Docker (with docker compose support)

• Python 3.11+ (for local development)

• Node.js 18+ (for MCP Inspector)

Installation

New to this project? See INSTALLATION.md for tested, step-by-step installation instructions.

Python Dependencies

# Development
pip install -e ".[dev]"

# Docker/Production
pip install -r requirements.txt

Project uses pyproject.toml for configuration.

Configuration (optional)

Create a .env file to customize paths:

cp .env.example .env
# Edit CVE_REPO_URL, CVE_REPO_PATH, CVE_GITHUB_API_BASE, CVE_DB_PATH

Works fine without any configuration.

Quick Start with Run Scripts (Recommended)

Convenient shell scripts automate the testing workflow:

Docker Testing (Full Workflow)

# 1. Build and start Docker container
./run_docker.sh

# 2. Load CVE data (choose one):
docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 100    # Quick
docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized                  # Full dataset

# 3. Test with MCP Inspector
./run_test_inspector.sh    # Choose option 2 (Docker)

Local Testing (Full Workflow)

# 1. Setup environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 2. Load CVE data (choose one):
./run_load_limited.sh              # Quick: 100 CVEs from 2024
./run_load_optimized.sh            # Full: ~240K CVEs (6-7 min)
./run_load_optimized.sh 2024 2023  # Specific years only

# 3. Test with MCP Inspector
./run_test_inspector.sh            # Choose option 1 (Local)

Available Run Scripts

Quick Start with Docker (Manual)

For detailed, tested step-by-step instructions, see INSTALLATION.md

1. Clone the Repository

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

2. Build Docker Image

sudo docker build -t cve-mcp-server .

Note: If you get "permission denied", either use sudo with all docker commands, or add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and log back in

3. Start Container

sudo docker compose up -d

Verify it's running:

sudo docker ps

4. Load CVE Data

sudo docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 100

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

5. Test with MCP Inspector

npx @modelcontextprotocol/inspector

Inspector configuration (if using sudo):

• Command: sudo

• Arguments: docker exec -i cve-mcp-server python -m src.mcp_server

• Environment: PYTHONPATH=/app

Inspector configuration (if in docker group):

• Command: docker

• Arguments: exec -i cve-mcp-server python -m src.mcp_server

• Environment: PYTHONPATH=/app

Note: If connection fails, restart MCP Inspector and try again.

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:

npx @modelcontextprotocol/inspector

Configuration:

• Command: python

• Arguments: -m src.mcp_server

• Environment: PYTHONPATH=/path/to/cve-mcp-server

5. Run Unit Tests

# Test database operations
python tests/test_database.py

# Test MCP tools directly
python tests/test_tools.py

Available Tools

get_cve_details

Get detailed information about a specific CVE.

Parameters:

• cve_id (string): CVE identifier like "CVE-2024-0001"

Example:

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

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 CVEs by keyword.

Parameters:

• keyword (string): Search term

• limit (integer): Max results, default 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 stats.

No parameters.

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

Using Run Scripts (Recommended)

Local development:

# Quick test with limited data
./run_load_limited.sh              # Default: 100 CVEs from 2024
./run_load_limited.sh 2023 50      # Custom: 50 CVEs from 2023

# Full dataset or specific years
./run_load_optimized.sh            # All ~240K CVEs (6-7 min)
./run_load_optimized.sh 2024 2023  # Only 2024 and 2023

Docker:

# Quick test
docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 100

# Full dataset
docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized

# Specific years
docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized --years 2024 2023

Manual Commands

Load More CVE Data (Local):

# Limited dataset via API
python -m src.data_ingestion.loader --year 2024 --limit 500

# Full dataset via Git clone
python -m src.data_ingestion.loader_optimized
python -m src.data_ingestion.loader_optimized --years 2024 2023

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

Performance & Benchmarks

Based on systematic benchmarking:

• Full dataset load time: ~6-7 minutes (240,000 CVEs)

• Database size: ~190 MB

• Loading speed: 2,700+ CVEs/second (using optimized loader)

Load Full Dataset

# Using optimized loader (recommended)
python -m src.data_ingestion.loader_optimized

# Or in Docker
docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized

See benchmarks/BENCHMARK_RESULTS.md for detailed analysis.

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 API CVE fetcher
│   │   └── loader_optimized.py  # Git clone CVE fetcher
│   └── config.py             # Configuration management
├── data/                     # SQLite database (Docker volume)
├── tests/                    # Unit tests
│   ├── test_database.py      # Database operation tests
│   └── test_tools.py         # Tool logic tests
├── run_load_limited.sh       # Quick data load script (API)
├── run_load_optimized.sh     # Full data load script (Git)
├── run_docker.sh             # Docker build and start script
├── run_test_inspector.sh     # MCP Inspector testing script
├── Dockerfile                # Container image definition
├── docker-compose.yml        # Container orchestration
├── pyproject.toml            # Project configuration (PEP 621)
├── requirements.txt          # Python dependencies
├── .env.example              # Configuration template
├── CLAUDE.md                 # Architecture documentation
├── TESTING.md                # Testing guide
└── 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)

• pyproject.toml: Modern Python project configuration (PEP 621)

Testing

Quick Testing with Run Script (Recommended)

Use the convenient testing script that handles both local and Docker deployments:

./run_test_inspector.sh

The script will:

1. Ask if you want to test Local or Docker deployment

2. Validate prerequisites (virtual environment, container running, database exists)

3. Display the correct MCP Inspector configuration

4. Launch MCP Inspector automatically

Manual Testing with MCP Inspector

MCP Inspector provides an interactive UI to test all tools:

1. Start the server (Docker or local)

2. Run npx @modelcontextprotocol/inspector

3. Configure connection (see Quick Start sections above)

4. Test each tool with various inputs

For detailed testing procedures, see TESTING.md.

Unit 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 with "unknown shorthand flag" error:

• Restart MCP Inspector completely (Ctrl+C and rerun npx @modelcontextprotocol/inspector)

• If using sudo for docker, set Command to sudo and Arguments to docker exec -i cve-mcp-server python -m src.mcp_server

• If in docker group, set Command to docker and Arguments to exec -i cve-mcp-server python -m src.mcp_server

Connection fails:

• Verify container is running: sudo docker ps

• Check exact command: sudo docker exec -i cve-mcp-server python -m src.mcp_server

• Ensure container name matches: cve-mcp-server

• Ensure PYTHONPATH environment variable is set to /app

Tools not appearing:

• Check server logs for import errors

• Verify PYTHONPATH is set correctly in Inspector environment variables

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

• Local only (stdio transport)

• Basic keyword search, no FTS5 yet

• Manual data refresh

• No auth/security (local use only)

TODO

Things that would be nice to add:

• SSE transport for network access

• SQLite FTS5 for better search

• Filter by CVSS score/severity/date ranges

• Automated data refresh (cron job?)

• Example UI with Streamlit or something

• Maybe a REST API wrapper

• CVE monitoring/alerts

• Export to PDF/CSV

• Stats dashboard

Contributing

Prototype project. PRs welcome for bug fixes, docs, or features from TODO list.

License

MIT - see LICENSE file

Credits

• CVE data from CVEProject/cvelistV5

• Built with Anthropic MCP SDK

Note: This is a prototype. For production use you'd want proper security, auth, error handling, etc.