MCP server (local)¶
The Model Context Protocol (MCP) lets an assistant call tools. The BreachSpider MCP server is a small program that runs on your own machine and gives assistants such as Claude Code, Claude Desktop and Cursor the BreachSpider device checks. Only vendor, product, version and a neutral asset id leave your machine.
For assistants that connect to a URL instead, see Hosted MCP.
Install¶
Package breachspider-mcp on PyPI, version 0.2.0 (November 2026), Python 3.10 or newer, MIT licensed. Install with pipx, which puts a breachspider-mcp command on your path:
# macOS
brew install pipx && pipx ensurepath
# Debian or Ubuntu
sudo apt install pipx && pipx ensurepath
# Windows (PowerShell)
py -m pip install --user pipx
py -m pipx ensurepath
Open a new terminal, then:
pipx install breachspider-mcp
To run it without installing, install uv and use uvx breachspider-mcp wherever this page says breachspider-mcp.
Your API key¶
Set BREACHSPIDER_API_KEY. A free 14 day trial key is at breachspider.com/developers; customers make keys on Integrations. The key is read only from the environment and never logged or returned.
Without a key the server runs in demo mode: public example access only, and every result says so.
Set it up¶
claude mcp add breachspider -e BREACHSPIDER_API_KEY="$BREACHSPIDER_API_KEY" -- breachspider-mcp
Add --scope user to use it in every project. Leave out -e ... for demo mode. Claude Code stores the key in its MCP configuration, and claude mcp get breachspider prints it: do not run that while sharing your screen.
Settings, Developer, Edit Config, then 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.
The same block in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
Tools¶
| Tool | What it does |
|---|---|
correlate_devices | CVEs for each device at its exact version, in priority order, with the fix plan, coverage, warnings, needs_review, an assessment sentence, result_hash and status_hash. Up to 25 devices per call |
check_changes | Cheap repeat check: which devices changed, and with status_hash, which changed status (known-exploited, lifecycle, firmware) and why. Up to 200 devices; a tenth of the cost |
get_fix_plan | Fix groups and fix plan for one device |
lookup_cve | BreachSpider's record for one CVE |
check_windows_host | Windows hosts against Microsoft's data, stored nowhere. Up to 25 hosts per call. Partner or customer key |
submit_device_batch | Queue up to 5,000 devices as one job and get a job_id. Keys with batch jobs enabled |
get_device_batch | Progress, then the summary and results page by page |
Trial keys can use the first four. All tools are read only except submit_device_batch, which queues a job and uses the key's allowance.
Try it¶
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 assistant calls correlate_devices and answers with three CVEs, all fixed by security patch 3.11.2, citing Moxa advisory MPSA-241156.
Privacy¶
Only vendor, product, version and an optional asset_id are sent (plus the hashes for check_changes, and the listed Windows fields for check_windows_host). Every other field is dropped before the request; fields that look identifying (host name, IP or MAC address, user, site, location, serial number) are listed under privacy.dropped_identifying_fields. An asset_id that is an IP, MAC or email address or a host name is replaced with a neutral id such as asset-1; tag-like ids such as PLC-LINE-2 are kept.
Honest results¶
An unresolved device, partial coverage, a product with no version data or an empty list is never reported as free of risk; needs_review is always passed through, and the tool descriptions tell the assistant to repeat each device's assessment. See Zero CVEs is not the same as no risk.
Errors¶
A failed call starts with one sentence the assistant acts on and ends with the API's retry_guidance (retryable, retry_after_seconds, action). The assistant is told never to retry when retryable is false. The server itself never retries.