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

InsightIDR — SIEM & Investigations

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.

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/:

Configuration

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

InsightVM

InsightIDR

Metasploit Pro

General

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

License

MIT — see LICENSE.