Velociraptor MCP Server

A production-ready Model Context Protocol (MCP) server for seamless integration between Velociraptor DFIR and Large Language Models (LLMs).

Why? Combine the power of Velociraptor's comprehensive digital forensics and incident response capabilities with the reasoning capabilities of large language models—enabling natural language queries and intelligent analysis of your forensic data.

✨ Key Features

• 🚀 Production-ready: Proper package structure, logging, error handling, and configuration management
• 🔐 Secure: JWT token management with automatic refresh
• 🌐 HTTP/2 Support: Built on modern async HTTP client with connection pooling
• 📊 Comprehensive API: Access Velociraptor artifacts, hunts, collections, and more
• 🎛️ Configurable: Environment variables, CLI arguments, and fine-grained tool filtering
• 📦 Pip installable: Install directly from GitHub releases or source

Table of Contents

• Quick Start
• Installation
• Configuration
• Usage
• Available Tools
• Development
• CI/CD
• Deployment
• Security
• Contributing
• License

Quick Start

1. Install

From GitHub (Recommended)

python -m venv .venv && source .venv/bin/activate
pip install git+https://github.com/socfortress/velociraptor-mcp-server.git

From Release Artifacts

1. Go to the Releases page
2. Download the latest .whl file
3. Install with:

pip install velociraptor_mcp_server-*.whl

From Build Artifacts (Latest Build)

1. Go to the Actions tab
2. Click on the latest successful workflow run
3. Download the python-package-distributions artifact
4. Extract and install:

pip install velociraptor_mcp_server-*.whl

2. Configure Environment

Create a .env file in your project directory:

# Velociraptor Server Configuration
VELOCIRAPTOR_API_KEY=/path/to/api.config.yaml
VELOCIRAPTOR_SSL_VERIFY=false
VELOCIRAPTOR_TIMEOUT=30

# MCP Server Configuration
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000

# Logging Configuration
LOG_LEVEL=INFO

# Tool Filtering (optional)
# VELOCIRAPTOR_DISABLED_TOOLS=CollectArtifactTool,RunVQLQueryTool

Note: For VELOCIRAPTOR_API_KEY, provide the full path to your Velociraptor api.config.yaml file. You can generate this file from your Velociraptor server using the admin interface or CLI.

3. Run the Server

# Using the CLI command
velociraptor-mcp-server

# Or using the Python module
python -m velociraptor_mcp_server

# With custom configuration
velociraptor-mcp-server --host 0.0.0.0 --port 8080 --log-level DEBUG

The server will start and be available at http://127.0.0.1:8000 (or your configured host/port).

Installation

Requirements

• Python 3.11 or higher
• Access to a Velociraptor server instance
• Network connectivity to your Velociraptor server
• Velociraptor API configuration file (api.config.yaml)

Development Installation

git clone https://github.com/socfortress/velociraptor-mcp-server.git
cd 

... [View full README on GitHub](https://github.com/socfortress/velociraptor-mcp-server#readme)