BreachSpider MCP server
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.
Tools
| Tool | Arguments | What it does |
|---|---|---|
correlate_devices |
assets (list of vendor, product, version, optional asset_id); optional confirmed_only, known_exploited_only, fix_available_only, max_findings |
CVEs for each device at its exact version, in priority order, with the fix plan, coverage, warnings, needs_review and a result_hash |
check_changes |
assets (as above, each with its stored result_hash) |
Cheap repeat check: get back which devices changed |
get_fix_plan |
asset (one vendor, product, version) |
Fix groups and fix plan for one device |
lookup_cve |
cve_id (for example CVE-2024-9137) |
BreachSpider's record for one CVE, trimmed |
check_windows_host |
assets (list of os_product, edition_id, os_build, architecture, optional installed_kbs, installation_type, esu_enrolled, display_version, asset_id); optional max_findings |
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 result_hash |
All five are read only. 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.
Install
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 ensurepath
-
Open a new terminal so the path change applies, then install:
pipx install breachspider-mcp
Option: run with uvx instead
To run it without installing, install uv first, then use
uvx breachspider-mcp wherever this README uses breachspider-mcp.
API key
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.
Setup
Claude Code
With the key in your shell's BREACHSPIDER_API_KEY variable:
claude mcp add breachspider -e BREACHSPIDER_API_KEY="$BREACHSPIDER_API_KEY" -- breachspider-mcp
If 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.
Claude Desktop
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.
Cursor
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" }
}
}
}
Example question
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.
Privacy
Only vendor, product, version and an optional asset_id (plus result_hash 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.
Honest results
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.
Trial limits and errors
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.
Development
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/list
BREACHSPIDER_BASE_URL points the server at another deployment (default https://breachspider.com).
License
MIT, same as the BreachSpider Python SDK. See LICENSE.
Metadata
Release files for breachspider-mcp 0.1.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| breachspider_mcp-0.1.7.tar.gz | 36.5 kB | With provenance | Details for breachspider_mcp-0.1.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| breachspider_mcp-0.1.7-py3-none-any.whl | Python 3 | none | any | Details for breachspider_mcp-0.1.7-py3-none-any.whl |
Total release size: 63.4 kB
Release files / breachspider_mcp-0.1.7.tar.gz
| Download URL | breachspider_mcp-0.1.7.tar.gz |
|---|---|
| Size | 36.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
faa2b7c84242441d7a95ed928e2746d6d96e6f089b466199a227ba91bd3e4f96
|
|
BLAKE2b-256 checksum How to use checksums |
1d9686c10d97ea1ff427022a53699d2ae1e22a983dd0f8bc78959230ed74b889
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / breachspider_mcp-0.1.7-py3-none-any.whl
| Download URL | breachspider_mcp-0.1.7-py3-none-any.whl |
|---|---|
| Size | 26.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3a00e8ad78888cc5cd7e290e55dc4ad05bebc063e3b1c7df6d17f8b6730c7ac5
|
|
BLAKE2b-256 checksum How to use checksums |
74c8b9a9a7444189810714806c8c941dbea23e622f09b4a484e04355daf06c88
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for breachspider-mcp 0.1.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for breachspider_mcp-0.1.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.