Rapid7 Bulk Export MCP

Análisis impulsado por IA para datos de Rapid7 Command Platform mediante MCP (Model Context Protocol) y AgentSkills.

Esta herramienta se ofrece como soporte de carácter voluntario ("best effort"); debido a la naturaleza personalizada y cambiante de las herramientas y flujos de trabajo que podrían utilizarla, no podemos ofrecer soporte ni orientación fuera del contenido del Código MCP y de AgentSkill.

¿Qué es esto?

Esta herramienta exporta datos de Rapid7 Command Platform a través de la Rapid7 Bulk Export API y los hace consultables en flujos de trabajo de GenAI y agentes.

• Servidor MCP: Incorpora herramientas que permiten obtener, procesar y consultar datos

• Agent Skill / Kiro Power: Aporta contexto adicional, conocimiento del esquema e instrucciones sobre cómo usar las herramientas MCP

• Base de datos DuckDB: Base de datos local basada en archivos para permitir consultas rápidas y estructuradas

Características

• Análisis impulsado por IA: Úselo con Kiro, Claude Desktop o cualquier asistente de IA compatible con MCP

• Carga de datos bajo demanda: Obtenga y cargue datos automáticamente desde Rapid7

• Reutilización de exportaciones: Reutiliza automáticamente las exportaciones del mismo día para evitar llamadas API redundantes

• Consultas en lenguaje natural: Haga preguntas en inglés sencillo

• Ejecución de consultas SQL: Ejecute consultas SQL complejas sobre vulnerabilidades, activos y otros datos

• Exploración de esquemas: Descubra los campos de datos disponibles

• Estadísticas e información: Obtenga resúmenes y distribuciones al instante

• Bloqueo de seguridad: Las consultas de los usuarios están en espacio aislado (sandbox): el acceso al sistema de archivos y a la red está deshabilitado a nivel del motor DuckDB

• Compatibilidad con Docker: Ejecútelo como servicio HTTP contenerizado para despliegues remotos o compartidos

Local vs Remoto

Puede ejecutar el servidor MCP en dos modos según su configuración:

Local (stdio) — El cliente de IA lanza el servidor como proceso hijo y se comunica a través de stdin/stdout. Esta es la opción predeterminada y la más sencilla. El servidor se ejecuta en su máquina, la base de datos vive junto a él y todo permanece local. Ideal para uso individual en una estación de trabajo o portátil.

Remoto (Docker / HTTP de streaming) — El servidor se ejecuta como un servicio HTTP contenerizado que expone un único endpoint /mcp. Los clientes se conectan a través de la red mediante URL. Ideal para entornos compartidos, uso en equipo o cuando quiera que el servidor se ejecute en una infraestructura dedicada separada de su herramienta de IA. Cabe señalar que esto hará que los datos sean compartibles entre todos los usuarios del MCP remoto; debe autenticar y proteger el endpoint /mcp.

Ambos modos usan las mismas herramientas MCP y controles de seguridad. La única diferencia es cómo se conecta el cliente.

Inicio rápido

0. Obtenga su clave API de Rapid7 y su región

Antes de empezar, necesitará las credenciales de su cuenta de Rapid7 Insight Platform.

Generar una clave API:

Importante: La clave API debe ser generada por un Administrador de la plataforma. La API de exportación masiva devuelve todos los datos de vulnerabilidades de toda la plataforma, por lo que se requiere acceso de nivel administrador.

1. Inicie sesión en Rapid7 Insight Platform como Administrador de la plataforma

2. Vaya a Administración → Administración de claves API

3. Elija el tipo de clave:

   • Clave de organización (recomendada): Permisos completos de administración (requiere el rol de Administrador de la plataforma)

   • Clave de usuario: Hereda los permisos de su cuenta; debe ser creada por un Administrador de la plataforma para tener acceso suficiente para las exportaciones masivas

4. Haga clic en "Generar nueva clave de administrador" (o "Generar nueva clave de usuario" si utiliza una cuenta de Administrador de la plataforma)

5. Seleccione su organización y proporcione un nombre para la clave

6. Copie la clave inmediatamente: no podrá volver a verla.

Encuentre su región:

Su región determina qué endpoint de API utilizar. Para encontrar su región:

1. Vaya a insight.rapid7.com e inicie sesión

2. Busque la etiqueta "Región de almacenamiento de datos" en la esquina superior derecha, debajo del nombre de su cuenta

Para más detalles, consulte:

• Managing Platform API Keys

• Product APIs and Regions

1. Configure su herramienta de IA

Elija su herramienta de IA a continuación. Cada guía explica cómo instalar el servidor MCP, añadir el Agent Skill y verificar la conexión.

Proteja su clave API: Evite almacenar su RAPID7_API_KEY en texto plano en el disco. Utilice un administrador de secretos para inyectar la clave en tiempo de ejecución; por ejemplo, 1Password CLI, Bitwarden CLI, macOS Keychain, Windows Credential Manager o PowerShell SecretManagement. Con 1Password puede establecer "command": "op" y "args": ["run", "--", "rapid7-mcp-server"] con referencias secretas op:// en el bloque env: la clave se resuelve desde su bóveda y nunca se escribe en archivos de configuración. Adapte este patrón al administrador de contraseñas que utilice.

Instalar el servidor MCP

1. Abra Claude Desktop y navegue a Personalizar → Conectores

2. Busque "Rapid7 Bulk Export" en el directorio de conectores

3. Haga clic en Instalar y proporcione su RAPID7_API_KEY y RAPID7_REGION cuando se le solicite

Instalar el Agent Skill

1. Vaya a Personalizar -> Habilidades

2. Haga clic en (+)

3. Crear habilidad

4. Subir habilidad

5. Suba el último archivo zip de la skill desde la versión de la derecha

Verificar

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

Instalar el servidor MCP

# 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

Configuración

Cree o edite .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"
      }
    }
  }
}

Instalar el Agent Skill

1. Abra el panel de Skills de Kiro (Paleta de comandos → "Kiro: Open Skills")

2. Haga clic en "Install from GitHub"

3. Introduzca la URL del repositorio: https://github.com/rapid7/rapid7-bulk-export-mcp/rapid7-bulk-export-skill

Active la skill en el chat con #rapid7-bulk-export-skill.

Verificar

1. Reinicie o vuelva a conectar los servidores MCP (Paleta de comandos → "MCP: Reconnect All Servers")

2. Compruebe en el panel MCP el servidor "rapid7-bulk-export" (debería mostrar "Connected")

3. Pruebe: #rapid7-bulk-export-skill Load the latest vulnerability data from Rapid7

Instalar el servidor MCP

# 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

Configuración

Use la CLI de Claude Code:

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

O edite manualmente ~/.claude.json (ámbito de usuario) o .mcp.json (ámbito de proyecto):

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

Use --scope user para acceso entre proyectos o --scope project para compartir en equipo.

Instalar el 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/rapid7-bulk-export-skill/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/rapid7-bulk-export-skill/SKILL.md \
  -o .claude/skills/rapid7-bulk-export/SKILL.md

O use npx skills para instalarlo directamente:

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

Claude Code detectará y usará automáticamente la skill cuando sea pertinente.

Verificar

1. Reinicie Claude Code o recargue la ventana

2. Escriba /mcp en el chat para comprobar el estado del servidor

3. Verifique que "rapid7-bulk-export" aparece en la lista

4. Pruebe: Load the latest vulnerability data from Rapid7

Instalar el servidor MCP

# 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

Configuración

Edite la configuración de MCP en VS Code:

• Use la Paleta de comandos: "MCP: Edit Configuration"

• O edite manualmente: .vscode/mcp.json (espacio de trabajo) o la configuración de usuario

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

Instalar el 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/rapid7-bulk-export-skill/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/rapid7-bulk-export-skill/SKILL.md \
  -o ~/.copilot/skills/rapid7-bulk-export/SKILL.md

O use npx skills para instalarlo directamente:

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

Use la skill como comando de barra: /rapid7-bulk-export.

Verificar

1. Recargue la ventana de VS Code

2. Compruebe el estado de MCP en la barra de estado o en el panel de salida

3. Pruebe: Load the latest vulnerability data from Rapid7

Instalar el servidor MCP

# 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

Configuración

Añada el servidor usando la CLI de Codex:

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

O edite manualmente ~/.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"

Si utiliza variables de entorno de su shell en lugar de codificarlas:

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

Verificar

1. Liste los servidores configurados: codex mcp list

2. Compruebe los detalles del servidor: codex mcp get rapid7-bulk-export

3. Pruebe: Load the latest vulnerability data from Rapid7

Instalar el servidor MCP

# 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

Configuración

Edite su archivo de configuración MCP de Antigravity:

• macOS/Linux: ~/.gemini/antigravity/mcp_config.json

• Windows: C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json

También puede acceder a este archivo desde el panel de Agente de Antigravity → "..." → Servidores MCP → Administrar servidores MCP → Ver configuración sin procesar.

Añada lo siguiente a mcp_config.json:

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

Verificar

1. Reinicie Antigravity para que los cambios surtan efecto

2. Abra el panel de Servidores MCP (menú "..." → Servidores MCP)

3. Confirme que "rapid7-bulk-export" aparece con las herramientas disponibles

4. Pruebe: Load the latest vulnerability data from Rapid7

Imagen de Docker

Utiliza la imagen base Red Hat UBI 10 Python 3.12 Minimal con Python 3.12.13 preinstalado. Compatible con sistema de archivos de solo lectura. No se requiere suscripción a Red Hat.

Compilar y ejecutar

Con docker compose (recomendado):

RAPID7_API_KEY=your-key RAPID7_REGION=us docker compose up -d

Con 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 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 su cliente MCP

Apunte cualquier cliente compatible con MCP al endpoint HTTP:

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

Instalar el Agent Skill

Siga la instalación de la skill para su herramienta de IA específica indicada anteriormente. La skill funciona igual independientemente de si el servidor MCP es local o remoto.

Verificar

1. Confirme que el contenedor está en ejecución: docker ps

2. Pruebe el endpoint: curl http://localhost:8000/mcp

3. Conecte su herramienta de IA y pruebe: Load the latest vulnerability data from Rapid7

2. Empiece a analizar

Nota: La primera exportación tarda entre 1 y 5 minutos según el tamaño de la organización. Una vez completada, los datos se almacenan en caché y las cargas posteriores reutilizan la misma exportación. Siempre puede solicitar actualizar los datos para obtener el conjunto más reciente.

Show me the top 10 critical vulnerabilities with known exploits

What's the severity distribution across my cloud assets?

Referencia de herramientas

start_rapid7_export

Inicia un nuevo trabajo de exportación en los servidores de Rapid7. Devuelve inmediatamente un ID de exportación. Admite tres tipos de exportación: vulnerability, policy y remediation.

Start a vulnerability export from Rapid7

check_rapid7_export_status

Consulta la API de Rapid7 una vez para obtener el estado actual de un trabajo de exportación. Úselo después de start_rapid7_export para saber cuándo están listos los datos.

Check the status of export abc-123

download_rapid7_export

Descarga los archivos Parquet de una exportación completada y los carga en la base de datos local DuckDB. Aquí es donde los datos se vuelven consultables.

Download and load export abc-123

load_rapid7_parquet

Carga archivos Parquet existentes directamente desde el disco (deben estar dentro de ~/.rapid7_mcp/imports/). Útil si ya tiene archivos exportados y desea omitir la llamada a la API.

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

query_rapid7

Ejecuta SQL sobre los datos cargados. La conexión se bloquea después de la carga: las lecturas y escrituras del sistema de archivos y el acceso a la red están bloqueados a nivel del motor DuckDB.

Tablas disponibles: assets, vulnerabilities, policies, vulnerability_remediation.

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

get_rapid7_schema

Devuelve los nombres de las columnas y los tipos de datos de todas las tablas cargadas. Úselo para comprender qué campos están disponibles antes de escribir consultas.

Show me the schema of the loaded data

get_rapid7_stats

Devuelve estadísticas resumidas: recuentos de filas, distribuciones de severidad, rangos de puntuación CVSS, recuentos de exploits y desgloses por proveedor de nube.

Give me an overview of the vulnerability data

list_rapid7_exports

Muestra el historial reciente de exportaciones con IDs, fechas, estados y recuentos de filas. Útil para encontrar una exportación anterior para volver a cargarla.

List my recent exports

purge_rapid7_data

Elimina permanentemente del disco tanto la base de datos de vulnerabilidades como la base de datos de seguimiento de exportaciones. Úselo cuando haya terminado el análisis o antes de entregar una máquina.

Purge all local Rapid7 data

Arquitectura

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

Desarrollo

Los cambios en AgentSkill y MCP se pueden realizar localmente para adaptarlos a su entorno; las contribuciones son bienvenidas de vuelta a este repositorio.

Clonar e instalar

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

Configurar para desarrollo

Cree o edite .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"
      }
    }
  }
}

Nota: Apunta command directamente al punto de entrada de venv en lugar de usar uv run con un cwd. Claude Desktop no garantiza un directorio de trabajo al lanzar servidores MCP, por lo que uv run puede resolverse a una versión en caché o instalada en el sistema del paquete en lugar de tu fuente local.

Ejecutar Pruebas

uv run pytest

Variables de entorno