Rapid7 Bulk Export MCP

AI-powered analysis for Rapid7 Command Platform data using MCP (Model Context Protocol) & AgentSkills.

This tool is a best effort support, due to the bespoke and ever-changing nature of tools and workflows which would utilize this tool we cannot provide support or guidance outside of the MCP Code & AgentSkill Content.

What is This?

This tool exports data from Rapid7 Command Platform, via the Rapid7 Bulk Export API and makes it queryable in GenAI and Agentic workflows.

• MCP Server: Embeds tools which allow the getting, processing and querying of data
• Agent Skill / Kiro Power: Gives additional context, schema knowledge and instructions on how to use the MCP tools
• DuckDB Database: Local file-based database to allow structured rapid querying

Features

• AI-Powered Analysis: Use with Kiro, Claude Desktop, or any MCP-compatible AI assistant
• On-Demand Data Loading: Automatically fetch and load data from Rapid7
• Export Reuse: Automatically reuses exports from the same day to avoid redundant API calls
• Natural Language Queries: Ask questions in plain English
• SQL Query Execution: Run complex SQL queries against vulnerability, asset and other data
• Multiple Export Types: Vulnerabilities (with vulnerability exceptions), policies, remediations, and installed asset software
• Multi-Month Remediation: Request any date range — it is split into ≤31-day windows and loaded for you in the background as a single job
• Schema Exploration: Discover available data fields
• Statistics & Insights: Get instant summaries and distributions
• Security Lockdown: User queries are sandboxed — filesystem and network access disabled at the DuckDB engine level
• Docker Support: Run as a containerized HTTP service for remote or shared deployments
• Remote Authentication: Remote mode validates OIDC bearer tokens against any standards-compliant identity provider

Local vs Remote

You can run the MCP server in two modes depending on your needs:

Local (stdio) — The AI client spawns the server as a child process and communicates over stdin/stdout. This is the default and simplest option. The server runs on your machine, the database lives next to it, and everything stays local. Best for individual use on a workstation or laptop.

Remote (Docker / streamable HTTP) — The server runs as a containerized HTTP service exposing a single /mcp endpoint. Clients connect over the network via URL. Best for shared environments, team use, or when you want the server running on dedicated infrastructure separate from your AI tool. It should be noted that this will make data shareable between all users of the remote mcp, you should authenticate and secure the /mcp endpoint — see docs/authentication.md for the built-in OIDC support and docs/copilot-studio-hosting.md for an example of a private hosted deployment.

Quick Start

0. Get Your Rapid7 API Key and Region

Before you begin, you'll need credentials from your Rapid7 Insight Platform account.

Generate an API Key:

Important: The API key must be generated by a Platform Admin. The bulk export API returns all vulnerability data across the entire platform, so admin-level access is required.

1. Log in to the Rapid7 Insight Platform as a Platform Admin
2. Navigate to Administration → API Key Management
3. Choose the key type:
   • Organization Key (recommended): Full admin permissions (requires Platform Admin role)
   • User Key: Inherits your account permissions — must be created by a Platform Admin to have sufficient access for bulk exports
4. Click "Generate New Admin Key" (or "Generate New User Key" if using a Platform Admin account)
5. Select your organization and provide a name for the key
6. Copy the key immediately - you won't be able to view it again!

Find Your Region:

Your region determines which API endpoint to use. To find your region:

1. Go to insight.rapid7.com and sign in
2. Look for the "Data Storage Region" tag in the upper right corner below your account name

For more details, see:

• Managing Platform API Keys
• Product APIs and Regions

1. Set Up Your AI Tool

Choose your AI tool below. Each guide walks through installing the MCP server, adding the Agent Skill, and verifying the connection.

Securing your API key: Avoid storing your RAPID7_API_KEY in plaintext on disk. Use a secrets manager to inject the key at runtime — for example, 1Password CLI, Bitwarden CLI, macOS Keychain, Windows Credential Manager, or PowerShell SecretManagement. With 1Password you can set "command": "op" and "args": ["run", "--", "rapid7-mcp-server"] with op:// secret references in the env block — the key is resolved from your vault and never written to config files. Adapt this pattern to whatever password manager you use.

Install the MCP Server

0. Open Claude Desktop and navigate to Customize → Connectors
1. Search for "Rapid7 Bulk Export" in the connectors directory
2. Click Install and provide your RAPID7_API_KEY and RAPID7_REGION when prompted

Install the Agent Skill

0. Go to Customize -> Skills
1. Click the (+)
2. Create Skill
3. Upload Skill
4. Upload the latest skill zipfile from the release on the right

Verify

1. Try: /rapid7-bulk-export-analysis-expert Load the latest vulnerability data from Rapid7

Install the MCP Server

# Using uv
uv pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

# Or using pip
pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

Configure

Create or edit .kiro/settings/mcp.json:

{
  "mcpServers": {
    "rapid7-bulk-export": {
      "command": "rapid7-mcp-server",
      "args": [],
      "env": {
        "RAPID7_API_KEY": "your-api-key-here",
        "RAPID7_REGION": "your-region"
      }
    }
  }
}

Install the Power (MCP + Skill)

This repository is packaged as an Agent Plugins power (plugin.json + mcp.json + skills/), so Kiro installs the MCP server declaration and the skill together:

1. Open the Kiro Powers panel → Add Custom Power
2. Select Import power from GitHub
3. Enter the repository URL: https://github.com/rapid7/rapid7-bulk-export-mcp

Kiro reads the keywords in plugin.json and activates the power automatically when you mention terms like "rapid7", "vulnerability", or "remediation". The power's mcp.json declares the rapid7-mcp-server stdio server; set RAPID7_API_KEY and RAPID7_REGION in your environment (the server inherits your shell; on macOS it can also read the key from Keychain). If you prefer to configure the MCP server by hand instead of via the power, use the .kiro/settings/mcp.json snippet shown above.

Verify

1. Restart or reconnect MCP servers (Command Palette → "MCP: Reconnect All Servers")
2. Check MCP panel for "rapid7-bulk-export" server (should show "Connected")
3. Try: Load the latest vulnerability data from Rapid7

Install the MCP Server

# Using uv
uv pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

# Or using pip
pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

Configure

Use the Claude Code CLI:

claude mcp add --transport stdio \
  --env RAPID7_API_KEY=your-api-key-here \
  --env RAPID7_REGION=your-region \
  rapid7-bulk-export \
  -- rapid7-mcp-server

Or manually edit ~/.claude.json (user scope) or .mcp.json (project scope):

{
  "mcpServers": {
    "rapid7-bulk-export": {
      "command": "rapid7-mcp-server",
      "args": [],
      "env": {
        "RAPID7_API_KEY": "your-api-key-here",
        "RAPID7_REGION": "your-region"
      }
    }
  }
}

Use --scope user for cross-project access or --scope project for team sharing.

Install the Agent Skill

# User-level (available in all projects)
mkdir -p ~/.claude/skills/rapid7-bulk-export
curl -sL https://raw.githubusercontent.com/rapid7/rapid7-bulk-export-mcp/main/skills/rapid7-bulk-export/SKILL.md \
  -o ~/.claude/skills/rapid7-bulk-export/SKILL.md

# Or project-level (only in current project)
mkdir -p .claude/skills/rapid7-bulk-export
curl -sL https://raw.githubusercontent.com/rapid7/rapid7-bulk-export-mcp/main/skills/rapid7-bulk-export/SKILL.md \
  -o .claude/skills/rapid7-bulk-export/SKILL.md

Or use npx skills to install directly:

npx skills install https://github.com/rapid7/rapid7-bulk-export-mcp

Claude Code will automatically discover and use the skill when relevant.

Verify

1. Restart Claude Code or reload the window
2. Type /mcp in chat to check server status
3. Verify "rapid7-bulk-export" appears in the list
4. Try: Load the latest vulnerability data from Rapid7

Install the MCP Server

# Using uv
uv pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

# Or using pip
pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

Configure

Edit MCP settings in VS Code:

• Use Command Palette: "MCP: Edit Configuration"
• Or manually edit: .vscode/mcp.json (workspace) or user settings

{
  "mcpServers": {
    "rapid7-bulk-export": {
      "command": "rapid7-mcp-server",
      "args": [],
      "env": {
        "RAPID7_API_KEY": "your-api-key-here",
        "RAPID7_REGION": "your-region"
      }
    }
  }
}

Install the Agent Skill

# Project-level (recommended, stored in repository)
mkdir -p .github/skills/rapid7-bulk-export
curl -sL https://raw.githubusercontent.com/rapid7/rapid7-bulk-export-mcp/main/skills/rapid7-bulk-export/SKILL.md \
  -o .github/skills/rapid7-bulk-export/SKILL.md

# Or user-level (available across all projects)
mkdir -p ~/.copilot/skills/rapid7-bulk-export
curl -sL https://raw.githubusercontent.com/rapid7/rapid7-bulk-export-mcp/main/skills/rapid7-bulk-export/SKILL.md \
  -o ~/.copilot/skills/rapid7-bulk-export/SKILL.md

Or use npx skills to install directly:

npx skills install https://github.com/rapid7/rapid7-bulk-export-mcp

Use the skill as a slash command: /rapid7-bulk-export.

Verify

1. Reload VS Code window
2. Check MCP status in the status bar or output panel
3. Try: Load the latest vulnerability data from Rapid7

Install the MCP Server

# Using uv
uv pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

# Or using pip
pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

Configure

Add the server using the Codex CLI:

codex mcp add rapid7-bulk-export \
  --env RAPID7_API_KEY=your-api-key-here \
  --env RAPID7_REGION=your-region \
  -- rapid7-mcp-server

Or manually edit ~/.codex/config.toml:

[mcp_servers.rapid7-bulk-export]
command = "rapid7-mcp-server"
args = []
enabled = true

[mcp_servers.rapid7-bulk-export.env]
RAPID7_API_KEY = "your-api-key-here"
RAPID7_REGION = "your-region"

If using environment variables from your shell instead of hardcoding them:

[mcp_servers.rapid7-bulk-export]
command = "rapid7-mcp-server"
args = []
enabled = true
env_vars = ["RAPID7_API_KEY", "RAPID7_REGION"]

Verify

1. List configured servers: codex mcp list
2. Check server details: codex mcp get rapid7-bulk-export
3. Try: Load the latest vulnerability data from Rapid7

Install the MCP Server

# Using uv
uv pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

# Or using pip
pip install git+https://github.com/rapid7/rapid7-bulk-export-mcp.git

Configure

Edit your Antigravity MCP config file:

• macOS/Linux: ~/.gemini/antigravity/mcp_config.json
• Windows: C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json

You can also access this file from the Antigravity Agent panel → "..." → MCP Servers → Manage MCP Servers → View raw config.

Add the following to mcp_config.json:

{
  "mcpServers": {
    "rapid7-bulk-export": {
      "command": "rapid7-mcp-server",
      "args": [],
      "env": {
        "RAPID7_API_KEY": "your-api-key-here",
        "RAPID7_REGION": "your-region"
      }
    }
  }
}

Verify

1. Restart Antigravity for changes to take effect
2. Open the MCP Servers panel ("..." menu → MCP Servers)
3. Confirm "rapid7-bulk-export" appears with available tools
4. Try: Load the latest vulnerability data from Rapid7

Docker Image

Uses Red Hat UBI 10 Python 3.12 Minimal base image with Python 3.12.13 pre-installed. Supports read-only filesystem operation. No Red Hat subscription required.

Build and Run

The HTTP transport requires inbound authentication and refuses to start without it, because an open /mcp endpoint would share your vulnerability data with anyone who can reach the port. Set the three MCP_AUTH_* values from your identity provider; docs/authentication.md explains where to find them.

Using docker compose (recommended):

RAPID7_API_KEY=your-key RAPID7_REGION=us \
MCP_AUTH_JWKS_URI=https://idp.example.com/keys \
MCP_AUTH_ISSUER=https://idp.example.com/ \
MCP_AUTH_AUDIENCE=api://rapid7-bulk-export \
docker compose up -d

Using docker run:

# Build
docker build -t rapid7-bulk-export-mcp .

# Run with read-only filesystem
docker run -d \
  -p 8000:8000 \
  -e RAPID7_API_KEY=your-api-key-here \
  -e RAPID7_REGION=us \
  -e MCP_AUTH_JWKS_URI=https://idp.example.com/keys \
  -e MCP_AUTH_ISSUER=https://idp.example.com/ \
  -e MCP_AUTH_AUDIENCE=api://rapid7-bulk-export \
  -e DATA_DIR=/data \
  -e TMPDIR=/tmp \
  -v rapid7-data:/data \
  --tmpfs /tmp \
  --read-only \
  --security-opt no-new-privileges:true \
  --name rapid7-bulk-export-mcp \
  rapid7-bulk-export-mcp

Configure Your MCP Client

Point any MCP-compatible client at the HTTP endpoint:

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

Install the Agent Skill

Follow the skill installation for your specific AI tool above. The skill works the same regardless of whether the MCP server is local or remote.

Verify

1. Confirm the container is running: docker ps
2. Test the endpoint: curl http://localhost:8000/mcp
3. Connect your AI tool and try: Load the latest vulnerability data from Rapid7

2. Start Analyzing

Note: The first export takes 1-5 minutes depending on org size. Once complete, the data is cached and subsequent loads reuse the same export. You can always ask to refresh the data to get the latest set.

Show me the top 10 critical vulnerabilities with known exploits

What's the severity distribution across my cloud assets?

Tool Reference

start_rapid7_export

Kicks off a new export job on Rapid7's servers. Returns immediately. Supports four export types: vulnerability, policy, remediation, and asset_software.

For remediation, pass a start_date and end_date (YYYY-MM-DD). Rapid7 limits each remediation export to 31 days and allows only one in flight at a time, so a longer range is split into ≤31-day windows and processed sequentially in the background as a single job. The call returns a job ID you poll with check_rapid7_export_status; all windows append into one vulnerability_remediation table.

Start a vulnerability export from Rapid7
Load remediation data from 2026-01-01 to 2026-06-30

check_rapid7_export_status

Reports status once, without blocking. Depending on what the ID names, it returns the Rapid7 platform-side export status, the local download/load progress once you have started loading, or the progress of a multi-window remediation job (which window is loading, and which windows are done). Accepts either an export ID or a remediation job ID.

Check the status of export abc-123

download_rapid7_export

Starts downloading a completed export's Parquet files and loading them into the local DuckDB database in the background, returning immediately — large exports can take longer than an AI client will wait on a single call. Poll check_rapid7_export_status with the same export ID until it reports the load is complete; that is when the data becomes queryable.

Download and load export abc-123

load_rapid7_parquet

Loads existing Parquet files directly from disk (must be within ~/.rapid7_mcp/imports/). Useful if you already have exported files and want to skip the API call.

Load parquet files from ~/.rapid7_mcp/imports/my-export/

query_rapid7

Executes SQL against the loaded data. The connection is locked down after loading — filesystem reads, writes, and network access are all blocked at the DuckDB engine level.

Available tables (depending on what you have loaded): assets, vulnerabilities, vulnerability_exceptions, policies, vulnerability_remediation, asset_software.

Run: SELECT severity, COUNT(*) FROM vulnerabilities GROUP BY severity

get_rapid7_schema

Returns column names and data types for all loaded tables. Use this to understand what fields are available before writing queries.

Show me the schema of the loaded data

get_rapid7_stats

Returns summary statistics — row counts, severity distributions, CVSS score ranges, exploit counts, and cloud provider breakdowns.

Give me an overview of the vulnerability data

list_rapid7_exports

Shows recent export history with IDs, dates, statuses, and row counts. Useful for finding a previous export to reload.

List my recent exports

purge_rapid7_data

Permanently deletes both the vulnerability database and the export tracking database from disk. Use when you're done with analysis or before handing off a machine.

Purge all local Rapid7 data

Architecture

graph TB
    subgraph "AI Layer"
        LLM[LLM/AI Assistant<br/>Copilot, Kiro, Claude Desktop, etc.]
    end

    subgraph "Rapid7 Bulk Export MCP Tool"
        MCP[MCP Server<br/>rapid7-bulk-export]
        Skill[Agent Skill / Power<br/>rapid7-bulk-export-skill]
    end

    subgraph "Data Layer"
        DB[(DuckDB<br/>rapid7_bulk_export.db)]
        Tracker[(Export Tracker<br/>rapid7_bulk_export_tracking.db)]
    end

    subgraph "Rapid7 API"
        R7[Rapid7 Bulk Export API<br/>/export/graphql ]
    end

    LLM <-->|Model Context Protocol| MCP
    LLM -.->|Enhanced Context| Skill
    MCP -->|SQL Queries| DB
    MCP -->|Track Exports| Tracker
    MCP -->|Fetch Data| R7
    R7 -->|Parquet Files| MCP
    MCP -->|Load Data| DB

    style LLM fill:#e1f5ff
    style MCP fill:#fff4e1
    style Skill fill:#f0e1ff
    style DB fill:#e8f5e9
    style Tracker fill:#e8f5e9
    style R7 fill:#ffe1e1

Development

Changes to the AgentSkill and MCP can be done locally to allow you to tailor to your environment — contributions are welcome back to this repository.

Clone and Install

git clone https://github.com/rapid7/rapid7-bulk-export-mcp.git
cd rapid7-bulk-export-mcp
uv sync

Configure for Development

Create or edit .kiro/settings/mcp.json:

{
  "mcpServers": {
    "rapid7-bulk-export": {
      "command": "/absolute/path/to/rapid7-bulk-export-mcp/.venv/bin/rapid7-mcp-server",
      "args": [],
      "env": {
        "RAPID7_API_KEY": "your-api-key-here",
        "RAPID7_REGION": "your-region",
        "DATA_DIR": "/Users/you/.rapid7-mcp"
      }
    }
  }
}

Note: Point command directly at the venv entry point rather than using uv run with a cwd. Claude Desktop does not guarantee a working directory when launching MCP servers, so uv run may resolve to a cached or system-installed version of the package instead of your local source.

Run Tests

uv run pytest

Environment Variables

Variable	Required	Default	Description
RAPID7_API_KEY	Yes	—	Rapid7 InsightVM API key
RAPID7_REGION	Yes	us	API region: us, us2, us3, eu, ca, au, ap
DATA_DIR	No	~/.rapid7_mcp	Directory for database files; must be writable. Manual parquet imports must be placed in $DATA_DIR/imports/
DUCKDB_MEMORY_LIMIT	No	4GB	Size of DuckDB's buffer pool, e.g. 4GB, 512MB. This bounds the buffer pool, not total process memory: peak usage runs roughly 1.8x this value with DUCKDB_THREADS=2 and up to 3.4x at the default thread count. Size it to about a third of the memory available to the container. Invalid values fall back to the default. Spill files are written to $DATA_DIR alongside the database
DUCKDB_THREADS	No	CPU count	Worker threads DuckDB may use. Each carries its own buffers, so lowering this is the most effective way to cut peak memory on a large load. 2 roughly halves peak memory for about 30% more load time. Values that are not a positive integer are ignored
MCP_TRANSPORT	No	stdio	Transport protocol: stdio or http
MCP_HOST	No	0.0.0.0	HTTP bind address (only when MCP_TRANSPORT=http)
MCP_PORT	No	8000	HTTP port (only when MCP_TRANSPORT=http)
MCP_AUTH_JWKS_URI	With http	—	Identity provider's JWKS endpoint. The HTTP transport refuses to start until this, MCP_AUTH_ISSUER and MCP_AUTH_AUDIENCE are set. See docs/authentication.md