BreachSpider MCP is a local read-only MCP server for checking devices against BreachSpider's device/CVE API.
Correlate devices: send vendor, product and version (no CPE) for one or more assets and get affected CVEs in priority order, fix plan, coverage, warnings, needs_review and result_hash; optionally filter to confirmed, known-exploited or fixable and limit findings.
Check changes: cheap repeat check for previously correlated devices using result_hash; returns which devices changed and their new hashes.
Get fix plan: fetch fix groups and the fix plan for a single device, including what clears known-exploited CVEs and all fixable issues.
Look up CVE: get a trimmed CVE record with severity, CVSS, known-exploited status, EPSS, fix status, vendor/CISA ICS advisories and links.
Privacy and honesty: only limited inventory fields are sent; identifying fields are stripped, and unresolved, partial or empty results are not reported as clean.
All exposed tools are read-only, idempotent, non-destructive and open-world.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BreachSpider MCP server which CVEs affect our Moxa EDS-518A switch on firmware V3.5, and what fixes them?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local, read only MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor and any other MCP client) check industrial and IT devices against the BreachSpider device API.
Give it a vendor, product and firmware version exactly as your inventory says. It returns the CVEs that affect that version, the affected range and where it comes from, the fix, the vendor advisory and a fix plan. No CPE strings needed.
Tool | Arguments | What it does |
|
| CVEs for each device at its exact version, in priority order, with the fix plan, coverage, warnings, |
|
| Cheap repeat check: get back which devices changed, and with |
|
| Fix groups and fix plan for one device |
|
| BreachSpider's record for one CVE, trimmed |
|
| Windows hosts against Microsoft's own patch data, stored nowhere: confirmed open, cleared and needs review counts, the top open and needs review CVEs with fixed build, KB and Microsoft source, fix groups and a |
|
| Queues one batch job for a long inventory and returns a |
|
| Progress while the job runs; once finished, the summary and a page of results (each the same as a |
All are read only except submit_device_batch, which queues a job and uses the key's quota. The first four use the three endpoints a trial key can call:
POST /api/v1/assets/correlate-cves, POST /api/v1/assets/correlate-cves/check and GET /api/v1/cves/{id}.
check_windows_host uses POST /api/v2/assets/check-windows, which stores nothing about the hosts and needs a
partner or customer key; trial keys and demo mode cannot use it. It takes at most 25 hosts per call.
The batch tools use POST /api/v1/batches and GET /api/v1/batches/{id} (and /results). They need a partner or
customer key with batch jobs enabled; trial keys and demo mode cannot use them. Results are kept 30 days.
Related MCP server: Security Intel MCP
Requires Python 3.10 or newer. Install with pipx, which puts a breachspider-mcp command
on your path.
Install pipx and add its folder to your path:
# macOS
brew install pipx
pipx ensurepath
# Debian / Ubuntu
sudo apt install pipx
pipx ensurepath
# Windows (PowerShell)
py -m pip install --user pipx
py -m pipx ensurepathOpen a new terminal so the path change applies, then install:
pipx install breachspider-mcpTo run it without installing, install uv first, then use
uvx breachspider-mcp wherever this README uses breachspider-mcp.
Set BREACHSPIDER_API_KEY to your key. Get a free 14 day trial key at
breachspider.com/developers.
With no key the server runs in demo mode: public example access only, using a short lived public demo token. Every result says so. For your own devices, start a free trial at breachspider.com/developers; for partner keys, use "Talk to us" on the same page.
The key is only read from the environment. It is never logged or returned in tool output.
With the key in your shell's BREACHSPIDER_API_KEY variable:
claude mcp add breachspider -e BREACHSPIDER_API_KEY="$BREACHSPIDER_API_KEY" -- breachspider-mcpIf you use uv instead of pipx, end the command with -- uvx breachspider-mcp.
Add --scope user to make it available in every project. Leave out -e ... for demo mode.
Claude Code stores the key in its MCP config, and claude mcp get breachspider prints it in plain text. Don't run
that command while sharing your screen or recording, and don't paste its output anywhere.
Edit claude_desktop_config.json (Settings, Developer, Edit Config) and restart Claude Desktop:
{
"mcpServers": {
"breachspider": {
"command": "/full/path/to/breachspider-mcp",
"env": { "BREACHSPIDER_API_KEY": "bs_live_your_key" }
}
}
}Use the full path from which breachspider-mcp; Claude Desktop does not read your shell path.
Add the same block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"breachspider": {
"command": "/full/path/to/breachspider-mcp",
"env": { "BREACHSPIDER_API_KEY": "bs_live_your_key" }
}
}
}We have a Moxa EDS-518A switch on firmware V3.5. Which CVEs affect it, are any known-exploited, and what version fixes them? Cite the sources.
The agent calls correlate_devices and answers with three CVEs, all fixed by security patch 3.11.2, citing
Moxa advisory MPSA-241156.
Is our Windows Server 2019 Standard on build 10.0.17763.6189 with KB5041578 installed missing any security updates? Which known-exploited CVEs are still open, and which update closes them?
The agent calls check_windows_host, reports the confirmed open count, the known-exploited CVEs first, the
cumulative update that clears them, and any CVEs that need review. Nothing about the host is stored.
Only vendor, product, version and an optional asset_id (plus result_hash, status_hash and the API's own status_facts for check_changes) are sent.
Any other field is dropped before the request. Fields that look identifying (host name, IP or MAC address, user,
site, location, serial number and similar) are listed in the output under privacy.dropped_identifying_fields.
For check_windows_host, only the Windows host fields listed in the tools table are sent, and the same
identifying-field rules apply. An asset_id that contains an IP, MAC or email address, or is a domain or fully qualified host name (for example
10.20.30.40 or sw-core-1.plant.example.com), is replaced with a neutral id such as asset-1. Tag-shaped ids such
as PLC-LINE-2 or plant-a-sw01 are kept, so results map back to your own equipment.
Each device gets an assessment sentence. An unresolved device, partial coverage, a product with no version data
or an empty list is never reported as clean, and needs_review is always passed through. Agents are told to
repeat this in their answer.
API errors come back as plain messages, including TRIAL_REQUIRED, TRIAL_SCOPE, TRIAL_BATCH_LIMIT
(25 devices per call on a trial), the trial limit (750 device checks; the message gives usage and when the trial
ends) and TRIAL_ENDED, each with a link to the developer page and a way to talk to us. check_changes costs a
tenth of a device check, so use it for repeat checks.
Every failed tool call starts with one sentence the agent acts on and ends with the API's retry guidance:
Do not retry this call; the trial has ended. Tell the user to start a new trial or ask for a partner key. TRIAL_ENDED: ...
retry_guidance: {"retryable": false, "retry_after_seconds": null, "action": "contact_us"}retryable is true only when the same call may succeed later (then the sentence is "Retry after N seconds.");
action is one of retry_later, wait_until_reset, reduce_batch, fix_input, use_different_key and
contact_us. The tool descriptions tell the agent never to retry when retryable is false. The server itself never
retries.
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest # unit tests (mocked) plus live demo mode tests
BREACHSPIDER_SKIP_LIVE=1 .venv/bin/python -m pytest # offline only
npx @modelcontextprotocol/inspector --cli .venv/bin/breachspider-mcp --method tools/listBREACHSPIDER_BASE_URL points the server at another deployment (default https://breachspider.com).
MIT, same as the BreachSpider Python SDK. See LICENSE.
Cheap repeat check. For devices you already checked with correlate_devices, send the same vendor, product and version plus the result_hash you kept. Returns which devices changed and their new hash; only changed devices need a fresh correlate_devices call. Use this for repeat checks. Never send host names, IP or MAC addresses, user names or site names.
Inputs: assets (required).
Find the CVEs that affect specific devices at their exact firmware or software version. Use this for any specific device and firmware. Send vendor, product and version exactly as the inventory says; no CPE is needed. Returns, per device: how it resolved, data coverage, an honest assessment, warnings, needs_review, result_hash (keep it for check_changes), the fix plan, and the top findings in priority order (known-exploited and confirmed first). Each finding gives the affected range with its source, the fix, advisory guidance and vendor advisories: cite the range source and the vendor advisory when explaining it. Report needs_review and partial coverage honestly and never call an empty, unresolved or partial result clean. Never send host names, IP or MAC addresses, user names or site names; such fields are stripped and listed under privacy.
Inputs: assets (required), max_findings, confirmed_only, fix_available_only, +1 more.
Fix plan for one device: fix groups (which update clears which CVEs) and the fix plan (the single step that clears the known-exploited CVEs, and the one that clears everything fixable). Send vendor, product and version exactly as the inventory says. Says so plainly when the device did not resolve or coverage is partial. Never send host names, IP or MAC addresses, user names or site names.
Inputs: asset (required).
Look up one CVE by id (for example CVE-2024-9137) and return BreachSpider's record, trimmed: severity, CVSS, known-exploited status, EPSS, fix status, vendor and CISA ICS advisories and links. It is not device specific; to know whether a device is affected, use correlate_devices.
Inputs: cve_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool has a fairly distinct purpose: correlate_devices (device-to-CVE mapping), check_changes (cheap re-check via result_hash), lookup_cve (single CVE by id), and get_fix_plan (per-device remediation). The one soft overlap is that correlate_devices already returns a fix plan in its output while get_fix_plan offers a dedicated per-device plan, which could cause an agent to hesitate; descriptions mostly resolve this.
All four tools follow a clean snake_case verb_noun pattern: correlate_devices, check_changes, lookup_cve, get_fix_plan. The convention is uniform throughout with no mixed styles or casing.
Four tools is lean but appropriate for a focused device-vulnerability correlation service, and each earns its place (correlate, re-check, CVE lookup, fix plan). It is on the thin side, with no room for batch or search operations.
The core lifecycle is covered: correlate devices, cheaply detect changes, look up individual CVEs, and get a fix plan. Minor gaps exist—no cross-cutting CVE search (by keyword/severity) or a tool to enumerate inventory—but the primary workflows are complete and the result_hash linkage is a thoughtful touch.
EOL dates, risk scores, CISA KEV exposure, SBOM audits and edge-device EOS for 700+ products.
Read-only CVE intelligence, remediation playbooks, and agent setup guides. Not a scanner.
Real-time CVE, exploit, and vulnerability intelligence for AI assistants (350K+ CVEs, 115K+ PoCs)
CVE lookups (NVD) and dependency-manifest audits (OSV) for AI agents. No API keys.
