CVE MCP Server

# 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 ```bash git clone https://github.com/yourusername/cve-mcp-server.git cd cve-mcp-server ``` ### 2. Build Docker Image ```bash docker build -t cve-mcp-server . ``` ### 3. Load CVE Data ```bash ./scripts/docker_load_data.sh ``` This downloads ~100 recent CVEs from GitHub (takes 1-2 minutes). ### 4. Start Container ```bash docker compose up -d ``` Verify it's running: ```bash docker ps ``` ### 5. Test with MCP Inspector ```bash 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 ```bash # Create virtual environment python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt ``` ### 2. Load CVE Data ```bash python -m src.data_ingestion.loader --year 2024 --limit 100 ``` ### 3. Run MCP Server ```bash 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: ```bash 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 ```bash # 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:** ```json { "cve_id": "CVE-2024-0001" } ``` **Example Response:** ```json { "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:** ```json { "keyword": "remote code execution", "limit": 10 } ``` **Example Response:** ```json { "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:** ```json { "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) ```bash # 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) ```bash python -m src.data_ingestion.loader --year 2024 --limit 500 ``` ### Check Database Status ```bash # 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](https://github.com/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 ```bash # Database operations python tests/test_database.py # Tool implementations python tests/test_tools.py ``` ## Troubleshooting ### Docker Issues **Container won't start:** ```bash docker logs cve-mcp-server docker compose down docker compose up -d ``` **No CVE data loaded:** ```bash ./scripts/docker_load_data.sh ``` **Rebuild after code changes:** ```bash 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](https://github.com/CVEProject/cvelistV5) - Built with [Anthropic MCP SDK](https://github.com/anthropics/anthropic-sdk-python) **Note**: This is a prototype project. For production use, consider implementing the TODO items, especially network security, authentication, and comprehensive error handling.