Velociraptor MCP Server

How to use

You connect your MCP client to the local or remote MCP server and start issuing DFIR and deployment commands through the available tools. Use endpoint search and inspection tools to enumerate Velociraptor clients, schedule artifact collection, create hunts across endpoints, and run VQL queries to retrieve data. Use pre-built DFIR prompts to guide investigations and deployment workflows to manage Velociraptor servers and agents across your infrastructure.

How to install

Prerequisites you need before installing the MCP server:

- Python 3.10 or higher

- A running Velociraptor server with API access enabled

Installation 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 and manual installs

# 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

Run the MCP server locally

You can start the server directly from your environment after installation.

megaraptor-mcp

Claude Desktop integration example

{
  "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 a VQL query: Run this VQL query: SELECT * FROM pslist() WHERE Name =~ 'suspicious'.

VQL Reference

VQL (Velociraptor Query Language) is the core query language. Common patterns include selecting clients, filtering by hostname, and retrieving running processes from collected data.

Example patterns: - List all clients: SELECT * FROM clients() - Get running processes: 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()

Deployment features

Automation covers server deployments and agent deployments across environments. You can deploy Velociraptor servers as binaries, via Docker, or to cloud platforms, and generate deployment packages for Windows and Linux/macOS agents.

Example deployment patterns include building an enterprise-grade deployment, generating GPO or WinRM agent packages, and creating Ansible playbooks for large-scale rollout.

Security and best practices

Follow least-privilege access for API clients. Encrypt deployment credentials at rest and protect CA certificates and private keys. Use key-based authentication where possible and limit exposure of MCP endpoints to trusted networks.

Notes on deployment and configuration

If you have a Velociraptor API client config, export the path to that file as VELOCIRAPTOR_CONFIG_PATH and point the MCP to it. You can run MCP locally with Python or via the installed command.

Troubleshooting

Check connectivity between the MCP server and Velociraptor server. Ensure your API client has the correct role permissions for the actions you attempt. Review logs for authorization errors and rate limits.

Notes

The MCP server supports a wide range of tools for endpoint management, artifact collection, hunts, flows, VQL execution, and deployment orchestration. Use the built-in prompts to guide workflows for investigation, threat hunting, triage, malware analysis, and deployment scaling.

list_clients

Search and list Velociraptor endpoints

get_client_info

Get detailed information about a client

label_client

Add or remove labels from clients

quarantine_client

Quarantine or release endpoints

list_artifacts

List available Velociraptor artifacts

get_artifact

Get full artifact definition

collect_artifact

Schedule artifact collection on a client

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

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

run_vql

Execute arbitrary VQL queries

vql_help

Get help on VQL syntax and plugins

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

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

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

store_credential

Securely store deployment credentials

list_credentials

List stored credential aliases

delete_credential

Remove stored credentials

download_velociraptor

Download Velociraptor binary for platform