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

All four are read only. They 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}.

Install

Requires Python 3.10 or newer.

pipx install breachspider-mcp

This puts a breachspider-mcp command on your path. Or run it without installing, with uv: uvx 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.

The key is only read from the environment. It is never logged or returned in tool output.

Setup

Claude Code

claude mcp add breachspider -e BREACHSPIDER_API_KEY=bs_live_your_key -- uvx breachspider-mcp

Add --scope user to make it available in every project. Leave out -e ... for demo mode.

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.

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. An asset_id that looks like a host name, address or email is replaced with a neutral id such as asset-1.

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.

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.