What can you do with this server?

The CVE MCP Server provides conversational access to a local, refreshable CVE database through three main tools: * Get CVE Details - Retrieve comprehensive information about specific CVEs by ID (e.g., CVE-2024-0001), including severity, CVSS score, description, published/modified dates, and references * Search CVEs - Perform keyword searches across CVE descriptions with configurable result limits (default 10, maximum 50 results) * Get Database Statistics - Query database metrics including total CVE count, date range of stored CVEs, and last update timestamp Key Features: * Fully Local & Private - All data stored locally with no external dependencies during queries * Refreshable Data - Load CVE data from official GitHub sources (CVEProject/cvelistV5) via quick limited loads or full dataset (~240K CVEs) * Flexible Deployment - Run in Docker containers for easy setup or locally via Python virtual environments * Fast Performance - Optimized loader processes 2,700+ CVEs/second, creating a ~190 MB database * MCP Protocol Compatible - Works with any MCP-compatible client including MCP Inspector and AI assistants * Testing & Development - Includes automated test scripts, unit tests, and comprehensive troubleshooting guides

Which integrations are available for this server?

Fetches and updates CVE (Common Vulnerabilities and Exposures) data from the GitHub CVEProject/cvelistV5 repository, enabling access to vulnerability information through natural language queries against a local database.

How do I use CVE MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CVE MCP Server show me details for CVE-2024-12345" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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

Script	Purpose	Usage
`run_load_limited.sh`	Load small dataset via API	`./run_load_limited.sh [year] [limit]`
`run_load_optimized.sh`	Load full/filtered dataset via Git	`./run_load_optimized.sh [year1] [year2] ...`
`run_docker.sh`	Build and start Docker container	`./run_docker.sh`
`run_test_inspector.sh`	Launch MCP Inspector for testing	`./run_test_inspector.sh`

Quick Start with Docker (Manual)

For detailed, tested step-by-step instructions, see

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:

Ask if you want to test Local or Docker deployment
Validate prerequisites (virtual environment, container running, database exists)
Display the correct MCP Inspector configuration
Launch MCP Inspector automatically

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

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.