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:

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

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.