mcp-velociraptor

Velociraptor MCP is a Proof-of-Concept bridge that exposes Velociraptor-based triage and DFIR tooling to MCP clients. It leverages Velociraptor's server API to run targeted queries and collection routines against a host or fleet, enabling natural-language prompts to trigger predefined Velociraptor actions (for example, listing network connections on a machine or identifying artifacts related to the USN journal). To use it, configure the bridge with your Velociraptor API client config, then run the Python bridge script from a virtual environment. The MCP client can then send requests that map to Velociraptor actions, which the bridge executes and returns results back to the MCP workflow. Typical interactions involve asking for specific data like active network connections on MACHINENAME or artifacts associated with the USN journal, which the bridge translates into Velociraptor API calls and formats for the MCP response.

Usage flow:

• Ensure Velociraptor API is accessible and you have an api_client.yaml configured with appropriate permissions.
• Start the bridge by invoking the configured Python path to mcp_velociraptor_bridge.py within your virtual environment.
• In MCP, prompt the system with natural language requests (e.g., ask for network connections on a specific machine or for USN journal artifacts); the bridge handles translating these into Velociraptor API actions and returns structured results.

Prerequisites:

• Python 3.8+ installed on the host
• Velociraptor server API accessible with a configured api_client.yaml
• A Python virtual environment prepared for the bridge

Installation steps:

1. Create and activate a Python virtual environment:

   • python3 -m venv veloci-mcp-venv
   • source veloci-mcp-venv/bin/activate

2. Install dependencies (if any are specified in the repository, e.g., requirements.txt):

   • pip install -r requirements.txt

3. Clone the mcp-velociraptor repository locally (or ensure the bridge script is accessible):

   • git clone https://github.com/your-org/mcp-velociraptor.git
   • cd mcp-velociraptor

4. Prepare Velociraptor API config:

   • Follow Velociraptor docs to generate api_client.yaml
   • Place api_client.yaml in a secure location and reference it in the bridge as VEL_API_CONFIG

5. Configure and run the bridge (example command shown in mcp_config):

   • /path/to/venv/bin/python /path/to/mcp_velociraptor_bridge.py

6. Test connectivity from MCP:

   • Ensure MCP can reach the bridge and that the bridge can reach Velociraptor's API endpoint.

Notes and caveats:

• This is a POC bridge; capabilities depend on Velociraptor’s API support and the data available on the target endpoints.
• Results may vary in size; filtering or batching of results may be necessary to fit MCP UI constraints.
• Ensure proper authentication and least-privilege for the Velociraptor API client to limit exposure.
• If you encounter connectivity issues, verify that the api_client.yaml path is correct and that network ACLs allow access from the bridge host to the Velociraptor server.
• The bridge currently maps common questions like querying network connections or USN journal artifacts; extend mappings as needed for additional use cases.