Metadata-Version: 2.4
Name: bibliocommons-mcp-insightvm
Version: 1.0.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
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

**Quick Links**: [Amazon Q](#amazon-q-developer-vs-code) | [Claude Desktop](#claude-desktop) | [VS Code](#vs-code-with-mcp-extension) | [GitHub Copilot](#github-copilot-vs-code) | [Cline](#cline-vs-code-extension) | [Zed](#zed-editor) | [Cursor](#cursor-ide) | [Kiro IDE](#kiro-ide) | [Kiro CLI](#kiro-cli)

### Amazon Q Developer (VS Code)

1. Install the Amazon Q extension in VS Code
2. Open VS Code Settings (JSON) and add:

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


**Alternative: Using python directly**

```json
{
  "amazonQ.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"]
    }
  }
}
```



### 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"]
    }
  }
}
```



### GitHub Copilot (VS Code)

1. Install GitHub Copilot extension in VS Code
2. Open VS Code Settings (JSON) and add:

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


**Alternative: Using python directly**

```json
{
  "github.copilot.chat.mcp.servers": {
    "rapid7-insightvm": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_insightvm"]
    }
  }
}
```



### Cline (VS Code Extension)

1. Install the Cline extension in VS Code
2. Open VS Code Settings (JSON) and add:

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


**Alternative: Using python directly**

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



### Zed Editor

1. Open Zed settings: `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows)
2. Navigate to "Language Models" → "Configure MCP Servers"
3. 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"]
    }
  }
}
```



### Cursor IDE

1. Open Cursor Settings (JSON): `Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"
2. Add the MCP 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"]
    }
  }
}
```



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

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

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