Velociraptor Forensic MCP Server

🦖 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.

!Python !Docker !Velociraptor !Tools !License

---

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.