Content
Tool List
Unified vulnerability search MCP service, providing one-stop vulnerability intelligence retrieval for penetration testing agents.
## Features
- **5 Major Data Sources**: NVD / OSV / EPSS / CISA KEV / Exploit-DB + GitHub
- **10 MCP Tools**: Covering CVE query, keyword search, batch query, EPSS assessment, KEV check, Exploit search, comprehensive judgment
- **English Output**: All tools return English Markdown format, with priority suggestions
- **Proxy Fallback**: Direct connection priority → automatic proxy fallback, suitable for network-limited environments
- **LLM Friendly**: Input fault tolerance (space/case/natural language) + error prompts with format examples and tool suggestions
## Installation
```bash
# Clone repository
git clone https://github.com/touful/touful-vuln-search-mcp.git
cd touful-vuln-search-mcp
# Install dependencies (including socks proxy support)
pip install -e .
```
## Configuration
Copy `.env.example` to `.env`, fill in API keys:
```env
NVD_API_KEY=your_nvd_api_key_here # Required, apply from https://nvd.nist.gov/developers
GITHUB_TOKEN=your_github_token_here # Optional, improve GitHub search quota
# HTTP_PROXY=socks5://127.0.0.1:7890 # Optional, enable when network is limited
```
| Variable | Required | Description |
|:---|:---|:---|
| `NVD_API_KEY` | ✅ | NVD API key, free application |
| `GITHUB_TOKEN` | ❌ | GitHub Personal Access Token, no permissions required |
| `HTTP_PROXY` | ❌ | Proxy address, supports socks5/http |
## Launch
```bash
# HTTP transport (default)
python -m src.server --transport http --host 127.0.0.1 --port 8080
# stdio mode (Claude Desktop / Cursor integration)
python -m src.server --transport stdio
MCP Client Configuration
** Desktop** (`claude_des.json`):
```json "mcpServers": "touful-vul": {
"command":",
"args": ["", "src.server",", "stdio"],
" "/path/to/toufuln-search-mcp",
": {
"N_KEY": "your-key",
ITHUB_TOKEN": "ghxxx",
"HTTP_PROXY": "socks5://127.0.1:789 }
}
}
## Tool List
| Tool | Purpose |
|:---|:---|
| `n_cve` | NVD single CVE details (CV/CPE/reference links)|
nvd_search_cve` | Search CVE by keyword |
| `nvd_get_c | NVD | Batchcomma-separated, up to 100)|
| `osv_query | OSV | Query known software packages |
| `_query_batch` | OSV software package vulnerabilities |
osv_get_vuln OSV | Query vulnerability details affected version range)|
|_epss_score` | EP 30-day exploitation probability| `check_` | CISA KEV | Check if in the catalog of known exploited vulnerabilities |
| `search_exploit` | GitHub+Exploit-DB | Search public PoC/Exploit |
| `assess_cve` | All 4 sources | 🎯 Comprehensive assessment (CVSS+EPSS+KEV+Exploit concurrent query)|
## Data Sources
| Data Source | Description | Authentication Required |
|:---|:---|:---|
| [NVD](nvd.nist.gov/) | National Vulnerability Database | Key |
| [](https://os/) | Google Open Database | No |
|](https://www.first.org/epss) | Expl Scoring System | No |
CISA KEV](https.cisa.gov/knownited-vulnerabilities-catalog Catalog of Known Exploitedabilities | No |
| [-DB](https://www-db.com/) + Git exploit code search | (optional)|
##
```
touful-v-search-mcp/
├── src/
│ ├── server.py MCP service entry, tool definitions
│ .py # Configuration management (environment variables/API endpoints)
│ /
│ ├── base.py Common base class (uniform error handling)
│ ├── http_utils # HTTP tools (direct proxy fallback)
│ ├──_client.py # N client (aiolimiter rate ├── osv_client OSV API client
epss_client.py EPSS API client
│ ├── kev_client.py # CISA KEV client
│ _client.py # Exploit search client
├── tests/ # Test scripts
│ ├── check_config.py # Configuration check
│ ├── check_tools.py # Tool availability check
│ ├── integration_test.py # Integration test
│ └── test_osv_format.py # OSV format test
├── scripts/ # Tools and test scripts
│ ├── check_cve_2024_1234.py # CVE status check│ ├── test_clients.py # Client function test
test_mcp_tools.py # MCP tool registration verification
│ ├── test_proxy_fallback Proxy fallback verification
│ ├── test_llm_robustness.py # LLM input robustness test
│ └── ... # scripts
├── docs/ # Documentation
├── pyproject.toml
├── .env.example
├── .gitignore
└── README.md
```
## Run Tests
```bash
# Check configuration correctness
python tests.py
# tool availability
python tests/check_tools.py
# Integration test
python tests/integration_test.py
# OSV format test
python tests/test_osv_format.py
```
## License
MIT
