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 — plus a broad GitHub platform layer and repo-wide dependency scanning.

✅ What makes this production-ready? See PRODUCTION-READY.md for details on async-safe caching, request coalescing, the killer composite scanning tool, and more.

---

Tools at a glance

Core vulnerability tools

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
correlate_vulnerability	NVD / OSV / GitHub / Snyk	Optional	Correlate the same CVE across multiple feeds and summarize the findings
check_package_vulns	OSV.dev	Optional	All known vulns for any npm/PyPI/Maven/Go package
search_github_advisories	GitHub GHSA	Optional	Search advisories by keyword, severity, ecosystem
snyk_test_package	Snyk	Required	Deep package scan — vuln count, patchability, upgrade paths
severity_bucket	Offline	None	CVSS score → severity label + remediation urgency
list_recent_cves	NVD	Optional	CVEs published in the last N days
cache_stats	Local	None	Debug: cache size + TTL

GitHub platform tools

MCP Tool	Source	Auth needed?	What it does
github_get_repo	GitHub REST	Optional	Repo metadata, security feature status, topics, license
github_list_issues	GitHub REST	Optional	List issues by state, labels, and page size
github_create_issue	GitHub REST	Required	File a bug/security issue from a tool workflow
github_get_pull_request	GitHub REST	Optional	Pull request details, files changed, review status
github_list_pull_requests	GitHub REST	Optional	List PRs by state and limit
github_search_code	GitHub Code Search	Required	Search public code for patterns and insecure snippets
github_get_file	GitHub REST	Optional	Fetch a repo file content safely via normalized path
github_list_workflows	GitHub REST	Optional	List GitHub Actions workflows in a repo
github_trigger_workflow	GitHub REST	Required	Trigger a workflow_dispatch event

Security superpowers

MCP Tool	Source	Auth needed?	What it does
scan_repo_dependencies	GitHub + OSV	Optional	Auto-discover manifest files and scan dependencies for OSV vulns
audit_repo_security_posture	GitHub REST	Optional	Run a 6-point security posture audit on a repo
pr_security_review	GitHub + heuristics	Optional	Scan PR diffs for security anti-patterns
create_vuln_issue	NVD + GitHub REST	Required	Create a formatted GitHub security issue for a CVE

---

Quick start

1 — Install dependencies

cd "<path-to-repo>"
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt

For macOS/Linux:

cd "<path-to-repo>"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For testing, install the development dependencies:

pip install -r requirements-dev.txt

2 — Run the test suite

$env:PYTHONIOENCODING="utf-8"
python -m pytest -q

3 — Use the local MCP client

You can also run the included mcp_client.py to launch the server and call tools directly.

python mcp_client.py --tool get_cve_details --args '{"cve_id":"CVE-2021-44228"}'
python mcp_client.py --tool search_cves --args '{"keyword":"Log4j","severity":"CRITICAL"}'
python mcp_client.py --list-tools

Run the server over HTTP/SSE for remote LLM clients:

python security_mcp_server.py --transport sse --host 0.0.0.0 --port 8000

---

Packaging & publication

This repository is already configured for packaging with pyproject.toml.

Publish to PyPI when you're ready:

python -m pip install --upgrade build twine
python -m build
python -m twine upload dist/*

Install the package locally during development:

pip install -e .

---

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:

$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:

$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:

$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:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

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

{
  "mcpServers": {
    "security-vuln": {
      "command": "python",
      "args": [
        "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"
      }
    }
  }
}

If your Python interpreter is not on PATH, use the full executable path instead of python.

For macOS/Linux, use the same command and args values inside your local Claude Desktop/MCP runner configuration.

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.

Correlate CVE-2021-44228 across NVD, OSV, GitHub advisories, and Snyk.

---

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 — 18 tools, 4 data sources
├── mcp_client.py            ← Local MCP client that launches the server and calls tools
├── test_client.py           ← Integration tests (9 tests, all passing)
├── requirements.txt         ← mcp + httpx
├── requirements-dev.txt     ← development/test dependencies
├── pyproject.toml           ← packaging metadata + pytest configuration
├── Dockerfile               ← containerized deployment image
├── .github/workflows/       ← CI workflow for tests
├── README.md                ← This file
└── .venv/                   ← Isolated Python environment

---

## Production deployment

This repository now includes first-class production deployment support.

### Docker deployment

Build the container:

```powershell
cd "<path-to-repo>"
docker build -t security-mcp-server .

Run it with your keys:

docker run --rm \
  -e NVD_API_KEY="$env:NVD_API_KEY" \
  -e GITHUB_TOKEN="$env:GITHUB_TOKEN" \
  -e SNYK_TOKEN="$env:SNYK_TOKEN" \
  -e CACHE_TTL_SECONDS=300 \
  -e LOG_LEVEL=INFO \
  security-mcp-server

The container starts the MCP stdio server directly, so it can be used with any host process that connects to its stdio streams.

Test and CI

• Run unit tests locally:

python -m pip install -r requirements-dev.txt
pytest

• CI is configured in .github/workflows/python-app.yml and runs tests on push and pull requests.

Configuration

Environment variables supported by production deploy:

• NVD_API_KEY — optional, increases NVD rate limits
• GITHUB_TOKEN — optional, raises GitHub API limits and enables write actions
• SNYK_TOKEN — required for snyk_test_package
• CACHE_TTL_SECONDS — cache TTL in seconds, default 300
• HTTP_TIMEOUT_SECONDS — upstream request timeout, default 20
• LOG_LEVEL — logging level, default INFO