A Model Context Protocol (MCP) server that exposes the U.S. CISA Known Exploited Vulnerabilities (KEV) catalog as a set of discoverable tools.

This repository provides a small stdio MCP server that fetches and validates the KEV catalog and exposes useful tools for searching, statistics, and ransomware-focused filtering. It's intended for local development, automation, and integration with MCP-capable clients (for example, Claude Desktop or editors with MCP support).

• Features
• Installation
• Usage
  • Run as MCP server
  • Development
• Tools (available via MCP)
• Scripts and Examples
• Development & Contributing
• Security & Data
• License

• Real-time KEV data (fetched from CISA)
• Flexible search (CVE, vendor, product, date ranges, keywords)
• Ransomware-focused filter (known campaign usage)
• Summary statistics and recent items
• MCP stdio transport for tool discovery and invocation
• Comprehensive scripts for automation and reporting
• Development examples and usage demonstrations

Prerequisites

• Node.js 18+ (LTS recommended)
• npm (or yarn)

Quick start

git clone https://github.com/52-devops/cisa-kev-catalog.git
cd cisa-kev-catalog
npm install
npm run build

If you plan to run the included VS Code helper extension, also install its dev deps:

cd vscode/cisa-kev-status
npm install
npm run build

Run as MCP server (production)

npm start

This starts a stdio MCP server (useful for MCP clients that spawn the server process).

Run in development (watch)

npm run dev

Using with VS Code (MCP clients)

1. Build once so dist/index.js exists

npm run build

1. Create .vscode/mcp.json with the servers key

{
  "servers": {
    "cisa-kev": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Alternatively, you can add the same mapping under .vscode/settings.json using the mcp.servers key:

{
  "mcp.servers": {
    "cisa-kev": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

1. Reload the window, then open Command Palette → "MCP: Run Tool" → select cisa-kev → pick a tool (e.g., get-recent-vulnerabilities) and provide inputs like { "days": 30 }.

StdIO and logging policy

• The MCP server writes only JSON-RPC frames to stdout. Any human-facing logs must go to stderr.
• Demo scripts and examples in this repo use process.stderr.write(...) for human-readable messages.
• When writing your own clients, avoid printing to stdout while the JSON-RPC session is active.

Troubleshooting (VS Code)

• If tools are not visible: ensure dist/index.js exists (run npm run build) and Node 18+ is used.
• If you see "Property mcpServers is not allowed.": VS Code expects the servers (or mcp.servers) key—do not use mcpServers in VS Code configs.
• Remove unknown properties like description from the MCP config.
• View → Output → pick "MCP" for logs. You can also start the server manually with npm start and retry discovery.

Optional: helper VS Code extension

• Location: vscode/cisa-kev-status/
• Purpose: adds a status bar control to start/stop the MCP server in an integrated terminal.
• Setup:

cd vscode/cisa-kev-status
npm install
npm run build

Using with Claude Desktop

In Claude's client config, use the mcpServers key to point to node ./dist/index.js with the repo as the working directory:

{
  "mcpServers": {
    "cisa-kev": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

The server advertises these tools. Each returns a JSON payload inside an MCP content block.

• get-kev-catalog-info — catalog metadata (title, version, dateReleased, count)
• get-kev-stats — totals, ransomware counts, top vendors, recent items
• search-vulnerabilities — searchable by cveId, vendor, product, dates, ransomwareUse, keyword
• get-vulnerability-by-cve — lookup a single CVE (cveId)
• get-recent-vulnerabilities — since N days (default 30)
• get-ransomware-vulnerabilities — convenience wrapper for ransomware-known items
• get-new-kves — get vulnerabilities added on a specific date (defaults to today)
• get-kve-due — get vulnerabilities with a due date equal to a specific date (defaults to today)

The following tool names were renamed to improve clarity:

• get-due-today-vulnerabilities is now get-kve-due
• get-today-vulnerabilities is now get-new-kves

If you have scripts or clients that call the old tool names, update them to use the new names. Example replacement:

{ "tool": "get-new-kves", "arguments": {} }

Usage example (MCP client): spawn the server and send JSON-RPC requests on stdio. See examples/mcp-client.js for a minimal client demo.

Examples (new tools)

• Get vulnerabilities added today (defaults to local today):

{ "tool": "get-new-kves", "arguments": {} }

• Get vulnerabilities added on 2025-09-11:

{ "tool": "get-new-kves", "arguments": { "date": "2025-09-11" } }

• Get vulnerabilities due today:

{ "tool": "get-kve-due", "arguments": {} }

This repository includes comprehensive scripts for automation and example usage.

Generate vulnerability reports automatically or on-demand:

Weekly Reports (scripts/weekly-report.js)

• Generates reports for vulnerabilities added in the past week
• Runs automatically every Monday at 9 AM or on-demand with --once
• Outputs Markdown and CSV formats

# Generate weekly report immediately
node scripts/weekly-report.js --once

# Start scheduled weekly reports (requires node-cron)
node scripts/weekly-report.js

Monthly Reports (scripts/monthly-report.js)

• Generates reports for vulnerabilities added in the last 30 days
• Runs automatically on the last day of each month or on-demand with --once
• Outputs Markdown and CSV formats

# Generate monthly report immediately
node scripts/monthly-report.js --once

# Start scheduled monthly reports
node scripts/monthly-report.js

Basic Service Test (test-basic.js)

• Simple smoke test for the CISA KEV service
• Validates service initialization and method availability
• Works with or without internet access (uses mocks when needed)

node test-basic.js

KEV Verification (scripts/verify-kev.js)

• Quick validation of KEV catalog connectivity
• Returns JSON output suitable for automation
• Focuses on ransomware-related vulnerabilities

node scripts/verify-kev.js
node scripts/verify-kev.js | jq '.total'  # Get count only

MCP Tool Testing (scripts/)

• dump-tools.js - Discovers and lists all available MCP tools
• call-get-kve-due.js - Tests the get-kve-due tool functionality

node scripts/dump-tools.js
node scripts/call-get-kve-due.js

Service Usage Examples (examples/usage-examples.js)

• Comprehensive demonstration of all service capabilities
• Shows various search patterns and filtering options
• Includes error handling and best practices

node examples/usage-examples.js

MCP Client Examples (examples/)

• mcp-client.js - Basic MCP client implementation
• mcp-demo.js - Interactive MCP tool demonstration
• Shows proper JSON-RPC communication patterns

node examples/mcp-client.js
node examples/mcp-demo.js

All scripts save their outputs to the reports/ directory:

• reports/weekly-vulns-YYYYMMDD.md - Weekly vulnerability reports
• reports/recent-vulns-YYYYMMDD.md - Monthly vulnerability reports
• reports/tools-list.json - Available MCP tools
• reports/get-kve-due.json - Tool test results

Helpful scripts

• npm run build — compile TypeScript to dist/
• npm run dev — run in dev/watch mode (tsx)
• npm test — run tests (Jest)
• npm run lint — run linter

Testing

• A smoke test ensures the MCP stdout stream contains only JSON when tools are called.
• Run tests with:

npm test

The smoke test file lives at __tests__/mcp-stdio.test.ts and spawns dist/index.js, sends tools/list and tools/call, and asserts all stdout lines are parseable JSON.

Repository layout

cisa-kev-catalog/
├─ src/                      # TypeScript source
├─ dist/                     # Compiled code (output)
├─ examples/                 # Usage demonstrations and client samples
├─ scripts/                  # Automation and reporting scripts
├─ reports/                  # Generated reports and output files
├─ vscode/                   # VS Code helper extension
├─ __tests__/                # Test files
└─ README.md

Contributing

1. Fork and branch
2. Add tests and documentation
3. Open a PR with a clear description and changes

• Data source: https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json
• The project validates input via Zod schemas and caches KEV responses for 1 hour.
• Do not ship secrets or credentials in this repo.

GPL-3.0 — see LICENSE