Security Scan MCP Server
by chrischabot
README.md
# Security Scan MCP
Security Scan MCP gives coding agents a security review checklist built from vulnerabilities that have actually happened. It is for developers who ask an agent to review their code and want that review to draw on more than the agent's general sense of what can go wrong. The National Vulnerability Database holds the relevant history in detail, but each CVE describes one bug in one product, which is hard to apply while reading a different codebase. This project does that translation ahead of time: Claude rewrites CVEs as generic review checks, the checks are grouped by the kind of software they apply to, and a [Model Context Protocol](https://modelcontextprotocol.io) server hands them to the agent on request.
Despite the name, it does not scan anything. An earlier version had an AST scanner, which was removed to concentrate on the prompts, and the `run-scan.ts` script still at the repository root no longer runs. The server tells an agent what to look for, and the agent still has to read the code and reach its own conclusions. The project is a prototype from January 2026. The bundled CWE lookups can be explored locally, while generating CVE-backed prompts still requires maintenance of the data pipeline.
## How it works
Two build steps produce a local SQLite database, and the server answers from it.
1. **Ingest.** `npm run ingest` seeds 40 CWE entries, then fetches HIGH and CRITICAL CVEs from the last five years through the NVD API, in the 120-day windows the API allows.
2. **Generate.** `npm run build-prompts` sends the CVEs to Claude 20 at a time. For each one, Claude assigns a generic software type such as `web-server` or `file-parser`, names the weakness, writes a check that applies to any code of that type, rates its severity and lists the code signals that identify that kind of software. Checks with the same type and title are merged, and each keeps the CVE IDs behind it.
3. **Serve.** The MCP server answers over stdio from the database described in [`src/db/schema.ts`](src/db/schema.ts), with SQLite FTS5 behind its search tools. At this stage it makes no network calls and needs no API keys.
Claude chooses the types, so the list is not fixed in advance and an agent starts by asking what exists. Reviewing an Express application, it would call `list_software_types`, match the routes and HTTP handling against the `code_signals` for `web-server`, and then call `get_security_prompts_for_type` to receive checks shaped like this one:
```json
{
"id": "web-server-1",
"title": "Header size validation",
"severity": "high",
"check_prompt": "Verify that HTTP header sizes are validated before processing...",
"based_on_cves": ["CVE-2021-xxxx", "CVE-2022-yyyy"]
}
```
## Getting started
You need Node.js 18 or later. The repository ships no CVEs or generated prompts: `data/vulnerabilities.db` holds only CWE entries. Start with the bundled CWE lookups, which need no API keys:
```bash
git clone https://github.com/chrischabot/security-scan-mcp.git
cd security-scan-mcp
npm install
npm run cli -- cwe 79
npm run cli -- top-cwes web
npm run cli -- stats
```
The CLI creates the local database if needed; `cwe` and `top-cwes` read their guidance directly from the bundled taxonomy. CVE and prompt lookups remain empty until you populate that database. [Generating CVE-backed prompts](#generating-cve-backed-prompts) describes the separate data pipeline and its current blockers.
To prepare the compiled MCP server, run:
```bash
npm run build
```
The compiler currently reports a missing argument at `src/cli.ts:261` and exits nonzero, although it still emits `dist/`. This is a known build defect. The server reads local data and does not require NVD or Anthropic credentials. To register it with Claude Code:
```bash
claude mcp add --transport stdio security-scan -- node /absolute/path/to/security-scan-mcp/dist/index.js
```
Other MCP clients can launch the same command over stdio:
```json
{
"mcpServers": {
"security-scan": {
"command": "node",
"args": ["/absolute/path/to/security-scan-mcp/dist/index.js"]
}
}
}
```
The `test-project/` directory holds deliberately vulnerable JavaScript, Python and React samples, which make a convenient first target for a review.
## Generating CVE-backed prompts
The generation pipeline needs maintenance before it is ready to use. The default ingest writes CVE/CWE mappings before their CVE rows and encounters CWEs outside the bundled set, violating the declared foreign keys. Fix the import ordering and missing-CWE handling rather than disabling those checks. The Claude client also hard-codes `claude-sonnet-4-20250514`, which Anthropic [retired in June 2026](https://platform.claude.com/docs/en/about-claude/model-deprecations); its model, request parameters and JSON output handling need updating and verification.
Generation needs your own [Anthropic API key](https://console.anthropic.com/) for paid calls and an [NVD API key](https://nvd.nist.gov/developers/request-an-api-key) for the ingest script. Copy `.env.example` to `.env` and fill in your own keys when working on that pipeline. Neither key is needed to serve an existing database.
The source provides these ingest modes: `npm run ingest` selects five years, `npm run ingest -- ingest 2` selects two years, and `npm run ingest -- update` selects CVEs modified in the last seven days. `npm run ingest -- seed` seeds the bundled CWEs without fetching CVEs. The seven-day window does not cap record counts or spending: `build-prompts` reads the whole local database through its search terms and sends batches of 20 CVEs to Claude.
Three other limits matter:
- `build-prompts` replaces existing prompts at the end, even if some or all batches failed. Errors are logged and skipped, and the scripts can exit successfully after logging failures. Inspect the summary and resulting database.
- It reads CVEs through nine broad search terms capped at 10,000 rows each, so a large database is not necessarily read in full.
- Replacing existing CVEs can leave stale FTS entries and cause `fts5: missing row`. With the `sqlite3` command installed, rebuild the index in the same data directory used by the server:
```bash
sqlite3 "${SECURITY_SCAN_DATA_DIR:-$HOME/.security-scan-mcp}/vulnerabilities.db" "INSERT INTO cve_fts(cve_fts) VALUES('rebuild');"
```
## MCP tools
| Tool | What it returns |
| --- | --- |
| `list_software_types` | Every generated type, with its description, code signals and prompt count |
| `get_security_prompts_for_type` | The checks for one type, optionally filtered by severity, as JSON or a Markdown checklist |
| `search_security_prompts` | Full-text search across all checks |
| `search_cves` | Full-text search across stored CVE descriptions |
| `get_cves_by_cwe` | Stored CVEs linked to a CWE, optionally filtered by severity |
| `get_cwe_info` | One of the 40 bundled CWE entries, with related stored CVEs |
| `get_top_cwes` | Selected entries from the 25 bundled weaknesses, 10 by default; accepts `limit` and an optional `web`, `api`, `cli`, `desktop`, `mobile`, `library` or `general` application filter |
| `get_database_stats` | CVE, CWE and prompt counts, plus the database path |
Search queries use FTS5 syntax, so quote anything containing punctuation, as in `"cross-site scripting"`. The bundled weakness list is modelled on the CWE Top 25 rather than copied from it, so check [MITRE's list](https://cwe.mitre.org/top25/) for official rankings and scores.
## Command line
The CLI offers the same lookups, which is useful for checking a build without an agent. Keep the `--`, because npm otherwise swallows flags such as `--severity`.
```bash
npm run cli -- help
npm run cli -- list-types
npm run cli -- get-prompts web-server --severity critical --checklist
npm run cli -- search-prompts "SQL injection"
npm run cli -- search-cves apache
npm run cli -- cwe 79
npm run cli -- top-cwes web
npm run cli -- stats
```
`cwe` and `top-cwes` read the bundled entries, so they work before you have built a database.
## Configuration
| Variable | Purpose |
| --- | --- |
| `ANTHROPIC_API_KEY` | Required by `npm run build-prompts` |
| `NVD_API_KEY` | Your NVD key, used by `npm run ingest` |
| `SECURITY_SCAN_DATA_DIR` | Directory holding `vulnerabilities.db`, by default `~/.security-scan-mcp` |
The build scripts read these from `.env` in the repository root. The CLI does not load `.env`, and the server looks for it in whichever directory your MCP client starts it from, so if you move the database, set `SECURITY_SCAN_DATA_DIR` in your shell and in the client's server configuration as well.
## Development
```bash
npm run dev # run the server from source with tsx
npm run build # compile to dist/
```
`npm test` and `npm run lint` are wired into `package.json`, but the repository has no test files or ESLint configuration yet.
## Project background
- [security-scan-mcp project overview](https://chabot.dev/projects/#security-scan-mcp) on Chris Chabot’s site.
## License and credits
Chris Chabot built this with Claude, which authored most of the commits in the public history. It is released under the [MIT License](LICENSE).
CVE data comes from the [National Vulnerability Database](https://nvd.nist.gov/). This product uses the NVD API but is not endorsed or certified by the NVD. CWE entries are based on MITRE's [Common Weakness Enumeration](https://cwe.mitre.org/).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues