rapid7-mcp

A unified MCP server for Rapid7's security platform — exposing InsightVM (vulnerability management), InsightIDR (SIEM/investigations), and Metasploit Pro (pentest telemetry) as tools for Claude, Cursor, and any MCP-compatible LLM client.

Ask natural-language questions across your entire Rapid7 environment — vulnerabilities, active incidents, compromised hosts — and get structured answers without writing a single API call.

Built with fastapi-mcp, FastAPI, and httpx.

No Rapid7 instance? Set DEMO_MODE=true to explore all 26 tools against realistic fixture data. Clone, run, connect — no credentials required.

---

What you can do

Once connected to Claude, you can ask things like:

"Which of my sites has the highest risk score?" "What are the critical vulnerabilities on the production web server, and is there already a remediation project for them?" "Is Log4Shell present anywhere in my environment? Show me the CVSS score and any available exploits." "Are there any open InsightIDR investigations right now? What's the highest priority one?" "Search our logs for any connections to this IP address: 185.220.101.1" "What active Metasploit sessions exist and what hosts were compromised?" "Give me a full security posture summary across sites, open incidents, and active sessions."

The server translates these into API calls across InsightVM, InsightIDR, and Metasploit Pro and returns structured data that Claude can reason over, correlate, and summarize.

---

Architecture

Claude / Cursor / MCP Client
        │  MCP (Streamable HTTP)
        ▼
┌───────────────────────────────────────────┐
│  FastAPI + fastapi-mcp  :8000             │
│                                           │
│  InsightVM        InsightIDR    MSP       │
│  ──────────────   ──────────    ───────── │
│  /sites           /idr/invest.  /workspcs │
│  /assets          /idr/logs     /sessions │
│  /asset_groups    /idr/iocs     /loot     │
│  /vulnerabilities                /tasks   │
│  /scans                                   │
│  /remediation_projects                    │
│  /reports                                 │
│                                           │
│  /mcp  ← MCP endpoint                    │
└──────┬──────────────┬──────────┬──────────┘
       │ Basic Auth   │ X-Api-Key│ Token
       ▼              ▼          ▼
  InsightVM      InsightIDR   Metasploit
  Console        Cloud API    Pro Console
  :3780          (regional)   :3790

Every FastAPI route is automatically published as an MCP tool via fastapi-mcp. Operation IDs become tool names, Pydantic schemas become input/output schemas, and docstrings become tool descriptions.

---

Quick Start

Prerequisites: Python 3.11+, uv

# 1. Clone and install
git clone https://github.com/SecuritahGuy/rapid7-mcp.git
cd rapid7-mcp
uv sync

# 2. Configure (or skip and use DEMO_MODE)
cp .env.example .env
# edit .env with your console URLs and credentials

# 3. Start the server
DEMO_MODE=true uv run uvicorn rapid7_mcp.main:app --port 8000

• MCP endpoint: http://localhost:8000/mcp
• Interactive API docs: http://localhost:8000/docs

---

Connect to VS Code

Add .vscode/mcp.json to your workspace (already included in this repo):

{
  "servers": {
    "rapid7-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Start the server first (Ctrl+Shift+P → Tasks: Run Task → Start MCP Server (Demo Mode)), then connect in the Claude Code panel.

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "rapid7": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Start the server first, then restart Claude Desktop.

---

Available MCP Tools

InsightVM — Vulnerability Management

Tool	Description
list_sites	List all scan sites — names, asset counts, risk scores, last scan time
get_site	Full details for a single site
list_asset_groups	Logical asset groupings (PCI scope, DMZ, dynamic OS groups)
get_asset_group	Details for a single asset group
get_asset	Asset details — IP, hostname, OS, vulnerability counts by severity, risk score
search_assets	Filter assets by IP, hostname, OS family, site ID, or tag
get_asset_vulnerabilities	All vulnerabilities found on a specific asset
get_asset_tags	Owner, environment, and compliance tags assigned to an asset
list_vulnerabilities	Browse the vulnerability library, filter by severity
get_vulnerability	Full vuln details — CVSS v2/v3, CVEs, exploit count, description
list_scans	Recent scans with status, duration, and vulnerability summaries
get_scan	Details for a single scan
list_remediation_projects	In-flight fix tracking — owner, due date, affected assets
get_remediation_project	Details for a single remediation project
list_reports	All configured reports (executive summaries, PCI exports, CSV)
get_report	Configuration and status for a single report
execute_report	Trigger on-demand report generation, returns download URI

InsightIDR — SIEM & Investigations

Tool	Description
list_investigations	Open security incidents — priority, status, assignee, alert summary
get_investigation	Full alert timeline for a specific investigation
query_logs	LEQL search across firewall, proxy, DNS, and endpoint logs
list_indicators	Active threat intelligence IOCs — IPs, domains, hashes, URLs

Metasploit Pro — Pentest Telemetry (read-only)

These tools are intentionally read-only. The LLM can see what Metasploit knows — active sessions, collected credentials, task status — but cannot execute exploits or interact with sessions.

Tool	Description
list_workspaces	All Metasploit Pro workspaces (pentest projects)
get_workspace	Details for a single workspace
list_sessions	Active Meterpreter and shell sessions — host, exploit, platform, username
get_loot	Credentials, hashes, and files extracted from compromised hosts
list_msp_tasks	Background tasks — scan imports, report generation, bruteforce jobs

---

Demo Mode

DEMO_MODE=true replaces all API calls with fixture data across all three products. No console, no credentials, no VPN.

Fixtures in tests/fixtures/:

Fixture	Contents
sites.json / site.json	3 sites: Production, Development, Cloud
assets.json / asset.json	Ubuntu and RHEL hosts with full vulnerability breakdowns
asset_groups.json / asset_group.json	PCI Scope, DMZ, Critical Infra, All Linux groups
asset_tags.json	Owner, environment, and compliance tags
vulnerabilities.json / vulnerability.json	Log4Shell, OpenSSL CVE-2022-0778, POODLE
asset_vulnerabilities.json	Vulnerabilities scoped to a single asset
scans.json / scan.json	One finished scan, one running
remediation_projects.json / remediation_project.json	Q1 patching sprint, Log4Shell project
reports.json / report.json / report_generate.json	Executive summary, PCI report, CSV export
investigations.json / investigation.json	PowerShell execution alert, SSH brute force
log_search_results.json	Firewall and proxy hits for a Tor exit node IP
indicators.json	Tor IP, Cobalt Strike hash, APT28 C2 domain
workspaces.json / workspace.json	Default workspace + Q1 external pentest
sessions.json	Meterpreter (SYSTEM) + shell (tomcat) sessions
loot.json	NTLM hashes + PostgreSQL credentials
msp_tasks.json	Completed InsightVM import + running report task

---

Configuration

All settings via environment variable or .env file. Copy .env.example to get started.

InsightVM

Variable	Default	Description
R7_CONSOLE_URL	https://localhost:3780	InsightVM console base URL
R7_USERNAME	admin	InsightVM user (Global Administrator role required)
R7_PASSWORD	password	InsightVM password
R7_VERIFY_SSL	false	Set to true if your console has a valid certificate

InsightIDR

Variable	Default	Description
IDR_REGION	us	Insight Platform region: us, us2, us3, eu, ca, au, ap
IDR_API_KEY	(empty)	Insight Platform API key

Metasploit Pro

Variable	Default	Description
MSP_URL	https://localhost:3790	Metasploit Pro console base URL
MSP_TOKEN	(empty)	MSP REST API token
MSP_VERIFY_SSL	false	Set to true if your MSP console has a valid certificate

General

Variable	Default	Description
DEMO_MODE	false	Return fixture data for all products; skips all live connectivity

---

Development

uv sync                                          # install deps + dev extras
uv run pytest --cov=rapid7_mcp tests/           # run tests with coverage
uv run ruff check . && uv run ruff format .      # lint + format
uv run mypy rapid7_mcp/                          # type check

See CONTRIBUTING.md for how to add a new tool, extend fixtures, and open a pull request.

Community & Project Health

• Security policy
• Code of Conduct
• Contributing guide
• Issue templates
• Pull request template
• Repository hardening checklist
• Wiki starter docs
• Wiki publishing guide

---

Tech Stack

Library	Why
fastapi-mcp	Converts FastAPI routes to MCP tools automatically — auth, deps, and schemas carry through
httpx	Async HTTP client, consistent with FastAPI's async model
pydantic-settings	Type-safe config from env vars and .env files
uv	Fast dependency management, becoming the standard for MCP Python projects
ruff	Replaces flake8 + black + isort in one tool

---

License

MIT — see LICENSE.