Vuln Nist MCP Server

1# vuln-nist-mcp-server
2 
3A Model Context Protocol (MCP) server for querying NIST National Vulnerability Database (NVD) API endpoints.
4 
5## Purpose
6 
7This MCP server exposes tools to query the NVD/CVE REST API and return formatted text results suitable for LLM consumption via the MCP protocol. It includes automatic query chunking for large date ranges and parallel processing for improved performance.
8 
9Base API docs: https://nvd.nist.gov/developers/vulnerabilities
10 
11## Features
12 
13### Available Tools
14 
15- **`get_temporal_context`** - Get current date and temporal context for time-relative queries
16  - Essential for queries like "this year", "last year", "6 months ago"
17  - Provides current date mappings and examples for date parameter construction
18  - **USAGE**: Call this tool FIRST when user asks time-relative questions
19 
20- **`search_cves`** - Search CVE descriptions by keyword with flexible date filtering
21  - Parameters: `keyword`, `resultsPerPage` (default: 20), `startIndex` (default: 0), `last_days` (`recent_days` has been deprecated), `start_date`, `end_date`
22  - **New in v1.1.0**: Support for absolute date ranges with `start_date` and `end_date` parameters
23  - **Date filtering priority**: `start_date`/`end_date` → `last_days` → default 30 days
24  - Auto-chunks queries > 120 days into parallel requests
25  - Results sorted by publication date (newest first)
26 
27- **`get_cve_by_id`** - Retrieve detailed information for a specific CVE
28  - Parameters: `cve_id`
29  - Returns: CVE details, references, tags, and publication dates
30 
31- **`cves_by_cpe`** - List CVEs associated with a Common Platform Enumeration (CPE)
32  - Parameters: `cpe_name` (full CPE 2.3 format required), `is_vulnerable` (optional)
33  - Validates CPE format before querying
34 
35- **`kevs_between`** - Find CVEs added to CISA KEV catalog within a date range
36  - Parameters: `kevStartDate`, `kevEndDate`, `resultsPerPage` (default: 20), `startIndex` (default: 0)
37  - Auto-chunks queries > 90 days into parallel requests
38  - Results sorted by publication date (newest first)
39 
40- **`cve_change_history`** - Retrieve change history for CVEs
41  - Parameters: `cve_id` OR (`changeStartDate` + `changeEndDate`), `resultsPerPage` (default: 20), `startIndex` (default: 0)
42  - Auto-chunks date range queries > 120 days into parallel requests
43  - Results sorted by change creation date (newest first)
44 
45### Key Features
46 
47- **Temporal Awareness**: New `get_temporal_context` tool for accurate time-relative queries
48- **Flexible Date Filtering**: Support for both relative (`last_days`) and absolute (`start_date`/`end_date`) date ranges
49- **Improved Result Ordering**: All results sorted chronologically (newest first) for better relevance
50- **Parallel Processing**: Large date ranges are automatically split into chunks and processed concurrently
51- **Input Validation**: CPE format validation, date parsing, parameter sanitization
52- **Emoji Indicators**: Clear visual feedback (✅ success, ❌ error, ⚠️ warning, 🔍 search, 🔥 KEV, 🌐 CPE, 🕘 history, 📅 temporal)
53- **Comprehensive Logging**: Detailed stderr logging for debugging
54- **Error Handling**: Graceful handling of API errors, timeouts, and malformed responses
55 
56## Prerequisites
57 
58- Docker (recommended) or Python 3.11+
59- Network access to NVD endpoints (`services.nvd.nist.gov`)
60- MCP-compatible client (e.g., Claude Desktop)
61 
62## Quick Start
63 
64### Using Docker (Recommended)
65 
66```bash
67# Clone and build
68git clone https://github.com/HaroldFinchIFT/vuln-nist-mcp-server
69cd vuln-nist-mcp-server
70docker build -t vuln-nist-mcp-server .
71 
72# Run
73docker run --rm -it vuln-nist-mcp-server
74```
75 
76## Configuration
77 
78Environment variables:
79 
80- `NVD_BASE_URL`: Base URL for NVD API (default: `https://services.nvd.nist.gov/rest/json`)
81- `NVD_VERSION`: API version (default: `/2.0`)
82- `NVD_API_TIMEOUT`: Request timeout in seconds (default: `10`)
83 
84## Usage Examples
85 
86### With Claude Desktop or MCP Client
87 
88**Get temporal context for time-relative queries:**
89```
90Tool: get_temporal_context
91Params: {}
92```
93 
94**Search recent CVEs (relative time):**
95```
96Tool: search_cves
97Params: {
98  "keyword": "Microsoft Exchange",
99  "resultsPerPage": 10,
100  "last_days": 7
101}
102```
103 
104**Search CVEs with absolute date range:**
105```
106Tool: search_cves
107Params: {
108  "keyword": "buffer overflow",
109  "start_date": "2024-01-01T00:00:00",
110  "end_date": "2024-03-31T23:59:59"
111}
112```
113 
114**Search CVEs for "this year" (use get_temporal_context first):**
115```
116# First, get temporal context
117Tool: get_temporal_context
118 
119# Then use the provided date mappings
120Tool: search_cves
121Params: {
122  "keyword": "remote code execution",
123  "start_date": "2025-01-01T00:00:00",
124  "end_date": "2025-09-17T12:00:00"
125}
126```
127 
128**Get CVE details:**
129```
130Tool: get_cve_by_id
131Params: {"cve_id": "CVE-2024-21413"}
132```
133 
134**Check CPE vulnerabilities:**
135```
136Tool: cves_by_cpe
137Params: {
138  "cpe_name": "cpe:2.3:a:microsoft:exchange_server:2019:*:*:*:*:*:*:*",
139  "is_vulnerable": "true"
140}
141```
142 
143**Find recent KEV additions:**
144```
145Tool: kevs_between
146Params: {
147  "kevStartDate": "2024-01-01T00:00:00.000Z",
148  "kevEndDate": "2024-03-31T23:59:59.000Z"
149}
150```
151 
152## Performance Notes
153 
154- Queries with date ranges > 90-120 days are automatically chunked for better performance
155- Parallel processing reduces total query time for large date ranges
156- Results are automatically sorted by publication date (newest first) across all chunks
157 
158## Development
159 
160### File Structure
161 
162```
163vuln-nist-mcp-server/
164├── Dockerfile
165├── glama.json
166├── LICENSE
167├── nvd_logo.png
168├── README.md
169├── requirements.txt
170├── SECURITY.md 
171└── vuln_nist_mcp_server.py
172```
173 
174## Security Considerations
175 
176- No API key required (public NVD endpoints)
177- Container runs as non-root user (`mcpuser`)
178- Input validation prevents injection attacks
179- No persistent storage of sensitive data
180- Network capabilities added only when required via Docker flags
181 
182## Contributing
183 
1841. Fork the repository
1852. Create a feature branch
1863. Make your changes
1874. Test locally
1885. Submit a pull request
189 
190## License
191 
192MIT - see LICENSE file for details
193 
194## Changelog
195 
196### v1.1.0
197- **NEW**: Added `get_temporal_context` tool for temporal awareness and time-relative queries
198- **ENHANCED**: `search_cves` now supports absolute date ranges with `start_date` and `end_date` parameters
199- **ENHANCED**: Improved date filtering logic with priority: absolute dates → relative days → default 30 days
200- **ENHANCED**: All tools now return results sorted chronologically (newest first) for better relevance
201- **IMPROVED**: Better error handling for ISO-8601 date parsing
202- **DEPRECATED**: `recent_days` parameter in `search_cves` (use `last_days` instead)
203- **UPDATED**: Logo and visual improvements
204 
205### v1.0.0
206- Initial release
207- Support for all major NVD API endpoints
208- Automatic query chunking and parallel processing
209- CPE format validation
210- Comprehensive error handling