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

License

MIT License - see LICENSE file for details.

Resources

Acknowledgments

The Velociraptor team at Velocidex for creating an amazing DFIR platform
Anthropic for the Model Context Protocol specification