🦖 Velociraptor Forensic MCP Server

Turn Claude Desktop into a DFIR workstation.

A unified Model Context Protocol (MCP) server that connects Claude Desktop to your Velociraptor instance AND local forensic tools. Remote endpoint investigation + local evidence analysis in one server. Docker deployment for Velociraptor included.

---

What This Does

Instead of switching between the Velociraptor GUI, terminal VQL sessions, and forensic scripts, you talk to Claude and it runs them for you. Ask Claude to:

• "Look up workstation-01 and tell me when it was last seen" → Queries Velociraptor for client info
• "Collect the user list from that endpoint" → Starts a Linux.Sys.Users artifact collection and retrieves results
• "Hash all files in /evidence/malware-samples/" → Recursively SHA-256 hashes a local directory
• "Check syslog for any mentions of that binary" → Scans system logs with keyword search
• "Cross-reference the file metadata with log entries" → Correlates timestamps, hashes, and log hits into a forensic report
• "Run a VQL query to show all running processes on the endpoint" → Executes custom VQL directly

All results come back in the chat. No copy-pasting. No tab switching. Full forensic chain from endpoint to evidence.

---

🛠️ Integrated Tools (12)

Remote — Velociraptor (vr_*)

Tool	Description
vr_authenticate	Test gRPC connection to Velociraptor
vr_get_agent_info	Look up a client by hostname → client_id, OS, agent version, last seen
vr_run_vql	Execute arbitrary VQL queries on the server
vr_list_artifacts	List all available client artifacts with descriptions
vr_artifact_details	Get full specs for a specific artifact
vr_collect_artifact	Start artifact collection on a remote endpoint (returns flow_id)
vr_get_collection_results	Poll and retrieve completed collection results (with retry logic)

Local Forensic (local_*)

Tool	Description
local_file_metadata	SHA-256, size, timestamps for a file (sandboxed to SAFE_BASE)
local_hash_directory	Recursively hash every file in a directory
local_scan_syslog	Search Linux syslog or macOS unified log by keyword
local_correlate	Cross-reference file metadata with log entries
local_forensic_report	Generate structured forensic report combining file + log data

Key Features

• Dual-mode: Either toolkit works independently — deploy with just Velociraptor, just local tools, or both
• Path sandboxing: All local_* tools validate paths stay within SAFE_BASE
• Async flow polling: Collection results auto-retry until the flow completes
• Multi-source artifacts: Handles artifacts with multiple data sources automatically
• Tool filtering: Disable individual tools via DISABLED_TOOLS env var
• Read-only mode: Block write operations (artifact collection) with READ_ONLY=true

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.11+
• Claude Desktop

1. Deploy Velociraptor (Docker)

cd docker/
docker compose up -d

# Wait ~30 seconds for initialization
docker logs velociraptor --tail 10
# Should see: "Starting gRPC API server" and "Frontend is ready"

Default GUI: https://localhost:9889 (admin/admin — change this!)

2. Generate API Key

chmod +x generate-api-key.sh
./generate-api-key.sh

This creates api.config.yaml with the gRPC credentials and automatically fixes the connection string for host access.

3. Install the MCP Server

cd ../
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

4. Configure

cp .env.example .env
# Edit .env — set your paths:
#   VELOCIRAPTOR_API_KEY=/path/to/api.config.yaml
#   SAFE_BASE=/home/youruser/evidence

5. Configure Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "velociraptor-forensic": {
      "command": "/path/to/velociraptor-forensic-mcp/.venv/bin/python",
      "args": ["-m", "velociraptor_forensic_mcp"],
      "cwd": "/path/to/velociraptor-forensic-mcp",
      "env": {
        "VELOCIRAPTOR_API_KEY": "/path/to/api.config.yaml",
        "VELOCIRAPTOR_SSL_VERIFY": "false",
        "SAFE_BASE": "/home/youruser/evidence",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

6. Restart Claude Desktop

The tools will appear automatically. Start investigating.

---

🔑 Environment Variables

Variable	Description	Default	Required
VELOCIRAPTOR_API_KEY	Path to api.config.yaml	—	For remote tools
VELOCIRAPTOR_SSL_VERIFY	Verify gRPC TLS certs	true
VELOCIRAPTOR_TIMEOUT	gRPC timeout (seconds)	30
SAFE_BASE	Root directory for local forensic tools	—	For local tools
MCP_SERVER_HOST	Bind host for SSE transport	127.0.0.1
MCP_SERVER_PORT	Bind port for SSE transport	8000
LOG_LEVEL	DEBUG/INFO/WARNING/ERROR	INFO
DISABLED_TOOLS	Comma-separated tool names to disable	—
READ_ONLY	Block artifact collection	false

---

🐳 Docker Velociraptor Setup

The docker/ folder contains everything to run Velociraptor in Docker with ports mapped to avoid common conflicts:

Host Port	Service	Purpose
9000	Client frontend	Velociraptor agent check-in
9001	gRPC API	MCP server connects here
9889	Web GUI	Your browser

Enrolling a Test Client

To enroll the machine running Docker as a Velociraptor client:

cd docker/

# Copy client binary and config
docker cp velociraptor:/velociraptor/clients/linux/velociraptor_client_repacked ./velociraptor_client
chmod +x velociraptor_client

docker exec velociraptor cat client.config.yaml > client.config.yaml
sed -i 's|https://VelociraptorServer:8000/|https://localhost:9000/|' client.config.yaml

# Run the client (Ctrl+C to stop)
sudo ./velociraptor_client --config client.config.yaml client -v

---

💡 Usage Examples

Full Endpoint Investigation

"Look up the endpoint pop-os, collect its user list, and check syslog for any suspicious entries"

Claude chains: vr_get_agent_info → vr_collect_artifact → vr_get_collection_results → local_scan_syslog

File Integrity Check

"Hash all files in /evidence/case-2024/ and check if any appear in the system logs"

Claude chains: local_hash_directory → local_correlate for each suspicious file

Custom VQL Investigation

"Run a VQL query to show me all listening network connections on client C.1393a876d1c48287"

Claude uses vr_collect_artifact with Linux.Network.Netstat or writes custom VQL via vr_run_vql

Quick Triage

"Scan syslog for 'authentication failure' and give me a summary"

Claude uses local_scan_syslog and synthesizes the results

---

📁 Project Structure

velociraptor-forensic-mcp/
├── velociraptor_forensic_mcp/
│   ├── __init__.py            # Package metadata
│   ├── __main__.py            # CLI entry point
│   ├── config.py              # Dataclass configs (Velociraptor, Forensic, Server)
│   ├── exceptions.py          # Custom exception hierarchy
│   ├── vr_client.py           # Velociraptor gRPC client
│   ├── forensic_helpers.py    # Local forensic functions
│   └── server.py              # FastMCP server with all tools/prompts/resources
├── docker/
│   ├── docker-compose.yaml    # Velociraptor Docker deployment
│   └── generate-api-key.sh    # API key generation script
├── tests/
│   └── test_forensic.py       # Unit tests
├── pyproject.toml             # Python packaging
├── .env.example               # Configuration template
└── README.md

---

🔒 Security

• API key protection: api.config.yaml contains a private key — chmod 600 it
• Path sandboxing: All local tools are restricted to the SAFE_BASE directory
• Least privilege: Generate API keys with --role api,investigator not administrator
• Tool filtering: Disable tools you don't need via DISABLED_TOOLS
• Read-only mode: Set READ_ONLY=true to prevent artifact collection
• Never commit api.config.yaml or .env to version control

---

🧪 Running Tests

source .venv/bin/activate
pytest -v

---

🏗️ Architecture

This server combines two open-source projects into a unified MCP interface:

• Remote tools adapted from socfortress/velociraptor-mcp-server (gRPC operations)
• Local tools adapted from axdithyaxo/mcp-forensic-toolkit (sandboxed file analysis)

Both toolkits activate independently based on which environment variables are set. You can run Velociraptor-only, local-only, or both together.

---

⚠️ Legal Disclaimer

This tool is intended for authorized digital forensics and incident response only. Always ensure you have proper authorization before collecting artifacts from endpoints. Unauthorized access to computer systems is illegal.

---

🤝 Contributing

Pull requests welcome. To add a new tool:

1. Add the function in forensic_helpers.py (local) or vr_client.py (remote)
2. Create a Pydantic input model in server.py
3. Register the tool in _register_forensic_tools() or _register_velociraptor_tools()
4. Add tests
5. Submit a PR

---

📬 Contact

• Discord: sgtwolf787
• GitHub: @Hackerobi

White hat or no hat 🎩

---

Built with Claude. Tested on live Velociraptor deployment. Stay legal.