Rapid7 InsightVM MCP Server

MCP server for interacting with Rapid7 InsightVM on-premise instances.

Configuration

Authentication: InsightVM API v3 uses HTTP Basic Authentication (username/password). It's recommended to create a dedicated API user account in InsightVM with appropriate permissions rather than using a personal account.

Option 1: config.json

cp config.json.example config.json
# Edit config.json with your API user credentials

Option 2: Environment Variables

export INSIGHTVM_HOST="insightvm.example.com:3780"
export INSIGHTVM_USERNAME="api-user"  # Dedicated API user account
export INSIGHTVM_PASSWORD="api-password"
export INSIGHTVM_VERIFY_SSL="true"

Installation

Option 1: Using uv (Recommended)

uv is a fast Python package manager. Install it first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

No additional installation needed - uvx will handle dependencies automatically.

Option 2: Using pip

pip install bibliocommons-mcp-insightvm
# or for development
pip install -e ".[dev]"

AI Client Setup

VS Code (with MCP Extension)

1. Install an MCP-compatible extension in VS Code
2. Open VS Code Settings (JSON): Cmd+Shift+P → "Preferences: Open User Settings (JSON)"
3. Add the server configuration:

{
  "mcp.servers": {
    "rapid7-insightvm": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/rapid7-insightvm", "bibliocommons-mcp-insightvm"]
    }
  }
}

Alternative: Using python directly

{
  "mcp.servers": {
    "rapid7-insightvm": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_insightvm"]
    }
  }
}

Claude Desktop

1. Open Claude Desktop configuration:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "rapid7-insightvm": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/rapid7-insightvm", "bibliocommons-mcp-insightvm"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "rapid7-insightvm": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_insightvm"]
    }
  }
}

Kiro IDE

1. Open Kiro IDE settings
2. Navigate to MCP Servers configuration
3. Add the server:

{
  "mcpServers": {
    "rapid7-insightvm": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/rapid7-insightvm", "bibliocommons-mcp-insightvm"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "rapid7-insightvm": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_insightvm"]
    }
  }
}

Kiro CLI

1. Create or edit the MCP configuration file:

   • User level: ~/.kiro/settings/mcp.json
   • Project level: <project-root>/.kiro/settings/mcp.json

2. Add the server configuration:

{
  "mcpServers": {
    "rapid7-insightvm": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/rapid7-insightvm", "bibliocommons-mcp-insightvm"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "rapid7-insightvm": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_insightvm"]
    }
  }
}

Configuration Notes

• Replace /absolute/path/to/rapid7-insightvm/ with the actual path to your server directory
• Using uvx (default): Automatically manages dependencies in isolated environments (like npx for Node.js)
• Using python (alternative): Requires pip install bibliocommons-mcp-insightvm first
• After adding the configuration, restart your AI client for changes to take effect

For other AI clients (Amazon Q, GitHub Copilot, Cline, Zed, Cursor), see docs/ai-clients.md.

Docker

# Pull from Docker Hub (private)
docker pull bibliocommons/mcp-insightvm:latest

# Run in stdio mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-insightvm:latest \
  --config /config.json

# Run in HTTP mode
docker run -d --rm \
  -v /path/to/config.json:/config.json:ro \
  -p 8000:8000 \
  bibliocommons/mcp-insightvm:latest \
  --config /config.json --transport http --port 8000

# Run in expanded mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-insightvm:latest \
  --config /config.json --expanded

Web UI with Swagger

A REST API with interactive Swagger documentation is available:

python -m bibliocommons_mcp_insightvm.webui

Access the Swagger UI at: [http://localhost:8000/docs]

The Web UI provides:

• Interactive API documentation
• Try-it-out functionality for all endpoints
• OpenAPI/Swagger specification
• REST API access to all MCP tools

Standalone MCP Server

python -m bibliocommons_mcp_insightvm

CLI Flags

Flag	Env Var	Description
--config PATH	INSIGHTVM_CONFIG	Path to config.json
--read-only	INSIGHTVM_READ_ONLY	Exclude destructive tools (start_scan, create/delete exceptions)
--expanded	INSIGHTVM_EXPANDED	Register all tools individually instead of gateway mode
--transport stdio|http	INSIGHTVM_TRANSPORT	Transport mode (default: stdio)
--port PORT	INSIGHTVM_PORT	HTTP port (default: 8000)
--version	—	Show version and exit

Gateway Mode (Default)

By default, the server exposes 2 tools instead of 30+ individual tools:

Tool	Purpose
insightvm_api	Execute any InsightVM action by name with a params dict
insightvm_help	Search available actions, parameters, and descriptions

The AI assistant calls insightvm_help to discover available actions, then calls insightvm_api(action="get_assets", params={"page": 0, "size": 10}) to execute them.

To register all individual tools (previous behavior), use --expanded:

python -m bibliocommons_mcp_insightvm --expanded

Available Tools

Assets

• get_assets - List all assets
• get_asset - Get asset by ID
• search_assets - Search assets with criteria
• get_asset_vulnerabilities - Get vulnerabilities for an asset
• get_asset_vulnerability_solution - Get solution for asset vulnerability

Vulnerabilities

• get_vulnerabilities - List vulnerabilities
• get_vulnerability - Get vulnerability by ID
• get_vulnerability_solutions - Get solutions for a vulnerability

Sites & Scans

• get_sites - List all sites
• get_site - Get site by ID
• get_scans - List scans for a site
• get_scan - Get scan by ID
• start_scan - Start a scan for a site

Scan Templates

• get_scan_templates - List all scan templates
• get_scan_template - Get scan template by ID

Scan Engines

• get_scan_engines - List all scan engines
• get_scan_engine - Get scan engine by ID

Reports

• get_reports - List all reports
• get_report - Get report by ID
• generate_report - Generate a report
• get_report_instance - Get report instance details

Solutions

• get_solution - Get solution by ID

Vulnerability Exceptions

• get_vulnerability_exceptions - List vulnerability exceptions
• get_vulnerability_exception - Get vulnerability exception by ID
• create_vulnerability_exception - Create vulnerability exception
• delete_vulnerability_exception - Delete vulnerability exception

Asset Groups

• get_asset_groups - List asset groups
• get_asset_group - Get asset group by ID

Users

• get_users - List all users
• get_user - Get user by ID

Tags

• get_tags - List all tags
• get_tag - Get tag by ID

Shared Credentials

• get_shared_credentials - List shared credentials
• get_shared_credential - Get shared credential by ID