Which integrations are available for this server?

Allows generating Ansible playbooks for automated deployment of Velociraptor agents across large-scale infrastructure. Provides tools for deploying and managing Velociraptor servers using Docker containers. Facilitates the deployment of Velociraptor agents to Linux systems via SSH for remote forensics and incident response tasks. Enables deployment of Velociraptor agents to macOS endpoints via SSH for conducting remote forensic investigations.

How do I use Megaraptor MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Megaraptor MCP search for the file hash a1b2c3d4e5f6 across all endpoints" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Megaraptor MCP

A Model Context Protocol (MCP) server that provides AI assistants with access to Velociraptor - the powerful digital forensics and incident response (DFIR) platform.

Overview

Megaraptor MCP enables AI assistants like Claude to interact with Velociraptor servers for:

Endpoint Management: Search, interrogate, and manage Velociraptor clients
Artifact Collection: Schedule forensic artifact collection on endpoints
Threat Hunting: Create and manage hunts across multiple endpoints
VQL Queries: Execute arbitrary Velociraptor Query Language queries
Incident Response: Pre-built DFIR workflow prompts for common scenarios
Deployment Automation: Deploy Velociraptor servers and agents across infrastructure (Docker, binary, cloud, GPO, SSH, WinRM, Ansible)

Features

MCP Tools (33 tools)

Core DFIR Tools (15 tools)

Category	Tool	Description
Clients	`list_clients`	Search and list Velociraptor endpoints
	`get_client_info`	Get detailed information about a client
	`label_client`	Add/remove labels from clients
	`quarantine_client`	Quarantine or release endpoints
Artifacts	`list_artifacts`	List available Velociraptor artifacts
	`get_artifact`	Get full artifact definition
	`collect_artifact`	Schedule artifact collection on a client
Hunts	`create_hunt`	Create a mass collection campaign
	`list_hunts`	List existing hunts
	`get_hunt_results`	Retrieve results from a hunt
	`modify_hunt`	Start, pause, stop, or archive hunts
Flows	`list_flows`	List collection flows for a client
	`get_flow_results`	Get results from a collection
	`get_flow_status`	Check collection status
	`cancel_flow`	Cancel a running collection
VQL	`run_vql`	Execute arbitrary VQL queries
	`vql_help`	Get help on VQL syntax and plugins

Deployment Tools (18 tools)

Category	Tool	Description
Server Deployment	`deploy_server_binary`	Deploy Velociraptor server as standalone binary
	`deploy_server_docker`	Deploy Velociraptor server using Docker
	`deploy_server_cloud`	Deploy Velociraptor server to AWS/Azure cloud
	`generate_server_config`	Generate server configuration with certificates
Agent Deployment	`deploy_agent_gpo`	Generate GPO deployment package for Windows
	`deploy_agent_winrm`	Deploy agents via WinRM to Windows endpoints
	`deploy_agent_ssh`	Deploy agents via SSH to Linux/macOS endpoints
	`deploy_agent_ansible`	Generate Ansible playbook for agent deployment
	`build_offline_collector`	Build standalone offline collector
	`generate_client_config`	Generate client configuration file
Deployment Management	`list_deployments`	List tracked deployment operations
	`get_deployment_status`	Get detailed status of a deployment
	`verify_deployment`	Verify deployment health and connectivity
	`rollback_deployment`	Rollback a failed deployment
Credentials	`store_credential`	Securely store deployment credentials
	`list_credentials`	List stored credential aliases
	`delete_credential`	Remove stored credentials
Utilities	`download_velociraptor`	Download Velociraptor binary for platform

MCP Resources

Browse Velociraptor data through standardized URIs:

velociraptor://clients - Browse connected endpoints
velociraptor://clients/{client_id} - View specific client details
velociraptor://hunts - Browse hunt campaigns
velociraptor://hunts/{hunt_id} - View specific hunt details
velociraptor://artifacts - Browse available artifacts
velociraptor://server-info - View server information
velociraptor://deployments - Browse deployment operations and status

MCP Prompts (8 prompts)

Pre-built DFIR and deployment workflow prompts:

Prompt	Category	Description
`investigate_endpoint`	DFIR	Comprehensive endpoint investigation workflow
`threat_hunt`	DFIR	Create and execute threat hunting campaigns
`triage_incident`	DFIR	Rapid incident triage and scoping
`malware_analysis`	DFIR	Analyze suspicious files or processes
`lateral_movement`	DFIR	Detect lateral movement indicators
`deploy_velociraptor`	Deployment	Interactive Velociraptor deployment wizard
`scale_deployment`	Deployment	Plan enterprise-scale agent rollout
`troubleshoot_deployment`	Deployment	Diagnose and fix deployment issues

Installation

Prerequisites

Python 3.10 or higher
A running Velociraptor server with API access enabled
API client credentials (see Configuration)

Install from source

git clone https://github.com/yourusername/megaraptor-mcp.git cd megaraptor-mcp # Core DFIR functionality only pip install -e . # With deployment features pip install -e ".[deployment]" # With cloud deployment (AWS/Azure) pip install -e ".[cloud]" # All features pip install -e ".[all]"

Optional Dependencies

Extra	Features	Packages
`deployment`	Agent/server deployment	paramiko, pywinrm, cryptography, jinja2
`cloud`	Cloud deployment	boto3, azure-mgmt-compute
`all`	All features	All of the above

Install dependencies manually

# Core only pip install mcp pyvelociraptor pyyaml grpcio # For deployment features pip install paramiko pywinrm cryptography jinja2 # For cloud deployment pip install boto3 azure-mgmt-compute azure-identity

Configuration

Megaraptor MCP supports two authentication methods:

Option 1: Config File (Recommended)

Generate an API client config on your Velociraptor server:

velociraptor --config server.config.yaml config api_client \ --name mcp-client \ --role reader,investigator \ api_client.yaml

Set the environment variable:

export VELOCIRAPTOR_CONFIG_PATH=/path/to/api_client.yaml

Option 2: Environment Variables

Set individual configuration values:

export VELOCIRAPTOR_API_URL=https://velociraptor.example.com:8001 export VELOCIRAPTOR_CLIENT_CERT=/path/to/client.crt # or PEM content export VELOCIRAPTOR_CLIENT_KEY=/path/to/client.key # or PEM content export VELOCIRAPTOR_CA_CERT=/path/to/ca.crt # or PEM content

API Roles

Assign appropriate roles to your API client based on required capabilities:

Role	Capabilities
`reader`	Read clients, artifacts, hunts, flows
`investigator`	Above + collect artifacts, create hunts
`administrator`	Full access (use with caution)

Usage

Running the Server

# Using the installed command megaraptor-mcp # Or as a Python module python -m megaraptor_mcp

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{ "mcpServers": { "velociraptor": { "command": "python", "args": ["-m", "megaraptor_mcp"], "env": { "VELOCIRAPTOR_CONFIG_PATH": "/path/to/api_client.yaml" } } } }

Example Interactions

List connected endpoints:

Use the list_clients tool to show all Windows endpoints

Investigate an endpoint:

Use the investigate_endpoint prompt for client C.1234567890abcdef

Create a threat hunt:

Create a hunt for the file hash a1b2c3d4e5f6... across all endpoints

Run custom VQL:

Run this VQL query: SELECT * FROM pslist() WHERE Name =~ 'suspicious'

VQL Reference

VQL (Velociraptor Query Language) is the core query language. Common patterns:

-- List all clients SELECT * FROM clients() -- Search for clients by hostname SELECT * FROM clients(search='host:workstation') -- Get running processes from collected data SELECT * FROM source(client_id='C.xxx', flow_id='F.xxx') -- Create a hunt SELECT hunt(artifacts='Windows.System.Pslist', description='Process audit') FROM scope()

For complete VQL reference, see: https://docs.velociraptor.app/vql_reference/

Deployment Features

Megaraptor MCP includes comprehensive deployment automation for Velociraptor infrastructure.

Server Deployment

Deploy Velociraptor servers using multiple methods:

Method	Use Case	Command
Binary	On-premise, direct installation	`deploy_server_binary`
Docker	Container environments, quick testing	`deploy_server_docker`
Cloud	AWS/Azure managed deployments	`deploy_server_cloud`

Example: Deploy Docker server

Deploy a Velociraptor server using Docker on server.example.com with SSH credentials "prod-server"

Agent Deployment

Multiple agent deployment methods for different environments:

Method	Target	Best For
GPO	Windows (Active Directory)	Enterprise Windows environments
WinRM	Windows (remote)	Windows without AD, smaller deployments
SSH	Linux/macOS	Unix-like systems
Ansible	Multi-platform	Large-scale infrastructure automation
Offline Collector	Air-gapped	Isolated networks, forensic collection

Example: Deploy agents via GPO

Generate a GPO deployment package for 500 Windows endpoints using the enterprise profile

Example: Deploy via Ansible

Create an Ansible playbook to deploy Velociraptor agents to all Linux servers in inventory.yml

Deployment Profiles

Pre-configured deployment profiles for different scenarios:

Profile	Use Case	Characteristics
rapid	Quick testing, POC	Minimal config, self-signed certs
standard	Production single-site	Proper certificates, standard hardening
enterprise	Large-scale multi-site	HA config, advanced monitoring, compliance

Credential Management

Securely store deployment credentials:

Store SSH credentials for prod-servers with username admin and key file ~/.ssh/prod_key

Credentials are encrypted at rest using AES-256-GCM with a locally-generated key.

Offline Collectors

Build standalone collectors for air-gapped environments:

Build an offline collector for Windows that collects browser history and network connections

Collectors include embedded configuration and can run without network connectivity.

Project Structure

megaraptor-mcp/ ├── pyproject.toml # Project configuration ├── README.md # This file ├── src/ │ └── megaraptor_mcp/ │ ├── __init__.py # Package initialization │ ├── __main__.py # Module entry point │ ├── server.py # MCP server main entry │ ├── client.py # Velociraptor API wrapper │ ├── config.py # Configuration handling │ ├── tools/ # MCP tool implementations │ │ ├── clients.py # Client management tools │ │ ├── artifacts.py # Artifact tools │ │ ├── hunts.py # Hunt management tools │ │ ├── flows.py # Flow/collection tools │ │ └── vql.py # VQL query tools │ ├── resources/ # MCP resource implementations │ │ └── resources.py │ ├── prompts/ # MCP prompt implementations │ │ └── prompts.py │ └── deployment/ # Deployment automation │ ├── __init__.py # Deployment module init │ ├── tools.py # Deployment tool implementations │ ├── server/ # Server deployment │ │ ├── __init__.py │ │ ├── binary.py # Binary deployment │ │ ├── docker.py # Docker deployment │ │ └── cloud.py # Cloud deployment (AWS/Azure) │ ├── agent/ # Agent deployment │ │ ├── __init__.py │ │ ├── gpo.py # GPO package generation │ │ ├── winrm.py # WinRM deployment │ │ ├── ssh.py # SSH deployment │ │ ├── ansible.py # Ansible playbook generation │ │ └── offline.py # Offline collector builder │ ├── credentials.py # Secure credential storage │ ├── config_generator.py # Config file generation │ └── profiles.py # Deployment profiles (rapid/standard/enterprise) └── tests/ # Test suite ├── test_config.py └── test_deployment.py

Security Considerations

API Security

API Credentials: Store API client credentials securely. The config file contains private keys.
Principle of Least Privilege: Use the minimum required roles for API clients.
Network Security: Ensure API connections are only accessible from trusted networks.
Audit Logging: Velociraptor logs all API actions. Review logs regularly.
Quarantine Caution: The quarantine tool can isolate endpoints from the network.

Deployment Security

Credential Encryption: Deployment credentials are encrypted at rest using AES-256-GCM. The .keyfile is generated locally and should be protected.
Generated Configs: Server and client configurations contain CA certificates and private keys. These are excluded from git via .gitignore.
Ansible Playbooks: Generated playbooks may contain CA certificates. Store securely and limit access.
Cloud Templates: CloudFormation and ARM templates may contain sensitive parameters. Review before committing.
SSH/WinRM: Use key-based authentication where possible. Avoid storing passwords in plain text.
Offline Collectors: Built collectors contain embedded configuration. Protect as you would agent binaries.
GPO Packages: MSI packages contain embedded configuration. Control access to distribution share.

Development

Running Tests

pip install -e ".[dev]" pytest

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request