CVE MCP Server

CVE MCP服务器（原型）

一种本地容器化的模型上下文协议（MCP）服务器，提供对CVE（常见漏洞和暴露）数据库的会话访问。

原型：这是一个演示MCP服务器实现的项目。它功能齐全，但尚未准备好生产。

概述

该项目允许使用任何兼容MCP的客户端对本地CVE数据库进行自然语言查询。所有数据都存储在本地以保护隐私，并且可以从公共CVE源刷新。

特性

• 完全本地-计算机上的所有数据，仅限stdio传输
• GitHub数据库中的可刷新CVE数据
• 在Docker中运行
• 与MCP检查员和其他MCP客户合作
• 三个工具： get_cve_details, search_cves, get_statistics

先决条件

• Docker（带 docker compose 支持）
• Python 3.11+（用于本地开发）
• Node.js 18+（用于MCP检查器）

安装

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

# Docker/Production
pip install -r requirements.txt

项目用途 pyproject.toml 用于配置。

配置（可选）

创建一个 .env 文件以自定义路径：

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

无需任何配置即可正常工作。

快速启动运行脚本（推荐）

方便的shell脚本自动化了测试工作流程：

Docker测试（完整工作流程）

# 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)

本地测试（完整工作流程）

# 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)

可用运行脚本

Docker快速入门（手册）

1.克隆存储库

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

2.构建Docker镜像

docker build -t cve-mcp-server .

3.加载CVE数据

./scripts/docker_load_data.sh

这将从GitHub下载约100个最近的CVE（需要1-2分钟）。

4.启动容器

docker compose up -d

验证它是否正在运行：

docker ps

5.使用MCP检查员进行测试

npx @modelcontextprotocol/inspector

检查器配置：

• 命令： docker
• 论据： exec -i cve-mcp-server python -m src.mcp_server
• 环境： PYTHONPATH=/app

本地开发（无Docker）

1.设置Python环境

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

# Install dependencies
pip install -r requirements.txt

2.加载CVE数据

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

3.运行MCP服务器

python -m src.mcp_server

服务器将通过stdio等待MCP客户端连接。

4.使用MCP检查员进行本地测试

在新终端中：

npx @modelcontextprotocol/inspector

配置：

• 命令： python
• 论据： -m src.mcp_server
• 环境： PYTHONPATH=/path/to/cve-mcp-server

5.运行单元测试

# Test database operations
python tests/test_database.py

# Test MCP tools directly
python tests/test_tools.py

可用工具

get_cve_details

获取特定CVE的详细信息。

参数：

• cve_id （字符串）：CVE标识符，如“CVE-2024-001”

例子：

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

答复：

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

按关键字搜索CVE。

参数：

• keyword （string）：搜索词
• limit （整数）：最大结果，默认值10

示例响应：

{
  "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_统计

获取数据库统计信息。

没有参数。

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

数据管理

使用运行脚本（推荐）

地方发展：

# 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

手动命令

加载更多CVE数据（本地）：

# 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

加载更多CVE数据（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

绩效和基准

基于系统基准：

• 完整数据集加载时间：约6-7分钟（240000个CVE）
• 数据库大小：约190 MB
• 加载速度：2700+CVE/秒（使用优化的加载器）

加载完整数据集

# 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

看 benchmarks/BENCHMARK_RESULTS.md 进行详细分析。

检查数据库状态

# 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()))
"

项目结构

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

使用的技术

• Python 3.11：核心语言
• MCP-SDK：模型上下文协议实现
• 数据库：具有全文搜索功能的本地数据库
• 码头工人：集装箱化和部署
• GitHub CVE数据库：数据来源(CVEProject/cvelistV5)
• pyproject.toml：现代Python项目配置（PEP 621）

测试

使用运行脚本进行快速测试（推荐）

使用方便的测试脚本来处理本地和Docker部署：

./run_test_inspector.sh

脚本将：

1. 询问您是要测试本地部署还是Docker部署
2. 验证先决条件（虚拟环境、容器运行、数据库存在）
3. 显示正确的MCP检查器配置
4. 自动启动MCP检查器

使用MCP检查员进行手动测试

MCP Inspector提供了一个交互式UI来测试所有工具：

1. 启动服务器（Docker或本地）
2. 跑 npx @modelcontextprotocol/inspector
3. 配置连接（请参阅上面的快速入门部分）
4. 使用各种输入测试每个工具

有关详细的测试程序，请参阅 TESTING.md.

单元测试

# Database operations
python tests/test_database.py

# Tool implementations
python tests/test_tools.py

故障排除

Docker问题

容器无法启动：

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

未加载CVE数据：

./scripts/docker_load_data.sh

代码更改后重建：

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

MCP检查器连接问题

连接失败：

• 验证容器是否正在运行： docker ps
• 检查确切命令： docker exec -i cve-mcp-server python -m src.mcp_server
• 确保容器名称匹配： cve-mcp-server

工具未出现：

• 检查服务器日志中的导入错误
• 验证PYTHONPATH是否设置正确

地方发展问题

导入错误：

• 确保虚拟环境已激活
• 检查PYTHONPATH是否包含项目根
• 验证已安装的所有依赖项： pip install -r requirements.txt

找不到数据库：

• 检查 data/cve.db 存在
• 运行数据加载器： python -m src.data_ingestion.loader

局限性

• 仅限本地（stdio传输）
• 基本关键字搜索，还没有FTS5
• 手动数据刷新
• 无身份验证/安全（仅限本地使用）

待办事项

很高兴添加以下内容：

• 用于网络接入的SSE传输
• SQLite FTS5用于更好的搜索
• 按CVSS评分/严重程度/日期范围筛选
• 自动数据刷新（cron作业？）
• 带有Streamlit或其他功能的示例UI
• 也许是REST API包装器
• CVE监控/警报
• 导出为PDF/CSV
• 统计仪表板

贡献

原型项目。欢迎PR从TODO列表中获取错误修复、文档或功能。

许可证

MIT-见许可证文件

鸣谢

• CVE数据来自 CVEProject/cvelistV5
• 内置于 拟人化MCP SDK

______________________________________________________________________

注：这是一个原型。对于生产使用，您需要适当的安全性、身份验证、错误处理等。