Skip to main content

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, a result_hash and a status_hash with its status_facts
check_changes assets (as above, each with its stored result_hash; optional status_hash and status_facts) Cheap repeat check: get back which devices changed, and with status_hash which ones changed status (known-exploited, lifecycle, firmware currency) and why
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
submit_device_batch assets (as for correlate_devices, up to 5,000); optional max_findings (default 10) Queues one batch job for a long inventory and returns a job_id at once. The same list sent again within 24 hours returns the original job, so a retry never charges twice
get_device_batch job_id; optional cursor, page_size (default 20, at most 50) Progress while the job runs; once finished, the summary and a page of results (each the same as a correlate_devices result) with next_cursor

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.

Install

Requires Python 3.10 or newer. Install with pipx, which puts a breachspider-mcp command on your path.

  1. 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
    
  2. 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, 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.

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.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for breachspider-mcp 0.3.0
File Size Uploaded Provenance Actions
breachspider_mcp-0.3.0.tar.gz 51.0 kB With provenance Details for breachspider_mcp-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for breachspider-mcp 0.3.0
File Interpreter ABI Platform Actions
breachspider_mcp-0.3.0-py3-none-any.whl Python 3 none any Details for breachspider_mcp-0.3.0-py3-none-any.whl

Total release size: 86.7 kB

Release files / breachspider_mcp-0.3.0.tar.gz

Download URL breachspider_mcp-0.3.0.tar.gz
Size 51.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2df1ff07d06ac441c48ff8378c8c195a9ce3f213302b2e98fa7a101944eba66f
BLAKE2b-256 checksum
How to use checksums
b4e5234d7bc935cb4ee64c5dc041addff8780851e21e437edc9f87c846bee9ec
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 Nov 8, 2026.

Transparency log

Release files / breachspider_mcp-0.3.0-py3-none-any.whl

Download URL breachspider_mcp-0.3.0-py3-none-any.whl
Size 35.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3d640cf9437809ad4d1dd281623f8e3266a3c439aade0a99675046bff0d26aa2
BLAKE2b-256 checksum
How to use checksums
ce94f6025a5dc0f51c17f95d04078882965099f35c6cc49a53351a267504dcc0
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 Nov 8, 2026.

Transparency log

Security for breachspider-mcp 0.3.0

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.

Select from 2 files

Attestation for breachspider_mcp-0.3.0.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 Nov 8, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page