# Security Vulnerability MCP Server

A **production-grade** Model Context Protocol server that gives Claude live access to four vulnerability databases — NVD, OSV, GitHub Security Advisories, and Snyk.

---

## Tools at a glance

| MCP Tool | Source | Auth needed? | What it does |
|---|---|---|---|
| `get_cve_details` | NVD | Optional | Full CVE record — score, description, weaknesses, references |
| `search_cves` | NVD | Optional | Keyword search with severity filter |
| `check_package_vulns` | OSV.dev | None | All known vulns for any npm/PyPI/Maven/Go package |
| `severity_bucket` | Offline | None | CVSS score → severity label + remediation urgency |
| `list_recent_cves` | NVD | Optional | CVEs published in the last N days |
| `search_github_advisories` | GitHub GHSA | Optional | Search 200K+ advisories by keyword, severity, ecosystem |
| `snyk_test_package` | Snyk | **Required** | Deep package scan — vuln count, patchability, upgrade paths |
| `cache_stats` | Local | None | Debug: cache size + TTL |

---

## Quick start

### 1 — Install dependencies

```powershell
cd "c:\Users\csc\OneDrive\Desktop\MCP Server"
.\venv\Scripts\activate
pip install -r requirements.txt
```

> venv is already created at `.\venv\` using Python 3.10.16

### 2 — Run the test suite

```powershell
$env:PYTHONIOENCODING="utf-8"
.\venv\Scripts\python.exe test_client.py
```

---

## API Key Setup Guide

### NVD API Key — *Free, highly recommended*

Without a key: **5 requests per 30 seconds**
With a key: **50 requests per 30 seconds** (10x improvement)

**Steps:**
1. Go to https://nvd.nist.gov/developers/request-an-api-key
2. Fill in your name and email — no payment needed
3. Check your email for the key (arrives in minutes)
4. Add to Claude Desktop config (see below) or set in PowerShell:

```powershell
$env:NVD_API_KEY = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

---

### GitHub Token — *Free, highly recommended*

Without a token: **60 requests per hour** (GitHub global unauthenticated limit)
With a token: **5,000 requests per hour**

The token only needs `public_repo` read scope — it never touches your private repos.

**Steps:**
1. Go to https://github.com/settings/tokens/new
2. Note (name): `security-mcp-server`
3. Expiration: choose how long (90 days or no expiration)
4. **Scopes**: check only `public_repo` — that's all that's needed
5. Click **Generate token** — copy it immediately (shown only once)
6. Add to Claude Desktop config or set in PowerShell:

```powershell
$env:GITHUB_TOKEN = "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

> **Tip**: For a more secure setup, use a *fine-grained personal access token* (also at https://github.com/settings/tokens) with *no repository access* — GitHub Advisories is a public API.

---

### Snyk Token — *Free tier available, required for snyk_test_package*

Free tier: **200 tests per month** — plenty for manual vulnerability checks.
Team/Business: unlimited tests + CI/CD integrations.

**Steps:**
1. Go to https://app.snyk.io — sign up free (GitHub, Google, or email)
2. After login, go to https://app.snyk.io/account
3. Under **Auth Token**, click **Click to show** → copy the token
4. Add to Claude Desktop config or set in PowerShell:

```powershell
$env:SNYK_TOKEN = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

---

## Wire into Claude Desktop

Find (or create) Claude Desktop's config file:

**Windows path:** `%APPDATA%\Claude\claude_desktop_config.json`

Open it in Notepad:
```powershell
notepad "$env:APPDATA\Claude\claude_desktop_config.json"
```

Add this block (replace the placeholder values with your actual keys):

```json
{
  "mcpServers": {
    "security-vuln": {
      "command": "C:\\Users\\csc\\OneDrive\\Desktop\\MCP Server\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\csc\\OneDrive\\Desktop\\MCP Server\\security_mcp_server.py"
      ],
      "env": {
        "NVD_API_KEY": "your-nvd-key-here",
        "GITHUB_TOKEN": "ghp_your-github-token-here",
        "SNYK_TOKEN": "your-snyk-token-here",
        "CACHE_TTL_SECONDS": "300"
      }
    }
  }
}
```

**Restart Claude Desktop** — you will see a hammer icon in the chat input bar indicating tools are active.

---

## Example Claude prompts to try

Once wired into Claude Desktop, try these in chat:

```
What are the most critical CVEs published this week?
```
```
Is lodash 4.17.20 vulnerable? Check via Snyk.
```
```
Search GitHub advisories for OpenSSL critical vulnerabilities.
```
```
Give me full details on CVE-2021-44228 and tell me how urgent it is.
```
```
Check if requests 2.25.0 (PyPI) has any known vulnerabilities.
```

---

## Production considerations

| Concern | What this server does |
|---|---|
| **Input validation** | CVE IDs checked against regex; severities/ecosystems checked against enums |
| **Caching** | TTL cache (default 5 min) keyed by CVE/query — survives repeated Claude calls |
| **Rate limiting** | Detects 429 responses, waits and retries with exponential backoff |
| **Retry / backoff** | Exponential backoff, max 3 attempts per call |
| **Error isolation** | Each tool catches exceptions; the MCP session never crashes |
| **Secrets** | API keys read from env vars only, never logged or echoed |
| **Structured logging** | Timestamped logs to stderr, visible in Claude Desktop logs |
| **Pagination** | `resultsPerPage` capped; `totalResults` returned for large datasets |
| **Graceful degradation** | Missing tokens return helpful setup instructions, not exceptions |

---

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `NVD_API_KEY` | *(empty)* | NVD API key — 10x rate limit increase |
| `GITHUB_TOKEN` | *(empty)* | GitHub PAT — 83x rate limit increase (60 → 5000 req/hr) |
| `SNYK_TOKEN` | *(empty)* | Snyk API token — **required** for `snyk_test_package` |
| `CACHE_TTL_SECONDS` | `300` | How long to cache upstream responses (seconds) |

---

## Project structure

```
MCP Server/
├── security_mcp_server.py   ← The server — 8 tools, 4 data sources
├── test_client.py           ← Integration tests (9 tests, all passing)
├── requirements.txt         ← mcp + httpx
├── README.md                ← This file
└── venv/                    ← Isolated Python 3.10.16 environment
```