Metadata-Version: 2.4
Name: bibliocommons-mcp-insightvm
Version: 1.2.0
Summary: MCP server for Rapid7 InsightVM vulnerability management
Author-email: Cody Lusk <cody.lusk@bibliocommons.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: requests>=2.33.1
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn>=0.46.0
Requires-Dist: python-multipart>=0.0.27
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: httpx>=0.28.1; extra == "dev"

# 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

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

### Option 2: Environment Variables

```bash
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](https://github.com/astral-sh/uv) is a fast Python package manager. Install it first:

```bash
# 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

```bash
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:

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

**Alternative: Using python directly**

```json
{
  "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:

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

**Alternative: Using python directly**

```json
{
  "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:

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

**Alternative: Using python directly**

```json
{
  "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:

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

**Alternative: Using python directly**

```json
{
  "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](docs/ai-clients.md).

## Docker

```bash
# 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:

```bash
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

```bash
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`:

```bash
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
