Skip to content
Back to search

mcp-velociraptor

VelociraptorMCP is a Model Context Protocol bridge for exposing LLMs to MCP clients.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mgreen27--mcp-velociraptor/badge.svg)](/listings/mgreen27--mcp-velociraptor)

HTML

<a href="/listings/mgreen27--mcp-velociraptor"><img src="/api/listings/mgreen27--mcp-velociraptor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Setup an API account

https://docs.velociraptor.app/docs/server_automation/server_api/

Generate an api config file:

`velociraptor --config /etc/velociraptor/server.config.yaml config api_client --name api --role administrator,api api_client.yaml`

2. Clone mcp-velociraptor repo and test API

- Copy `api_client.yaml` to the repo root, or keep it anywhere local and set `VELOCIRAPTOR_API_CONFIG=/path/to/api_client.yaml`. - Copy `example.env` to `.env` for local development, then set `VELOCIRAPTOR_API_CONFIG` to your real `api_client.yaml` path. The bridge, smoke script, and agent load dotenv config automatically without overriding variables already supplied by your shell or MCP client. - `api_client.yaml` is gitignored and should not be committed. - Run `.venv/bin/python test_api.py` to confirm the API works when `.env` is configured, or use `VELOCIRAPTOR_API_CONFIG=/path/to/api_client.yaml .venv/bin/python test_api.py` to override it for a single run. - The MCP bridge reads the same `VELOCIRAPTOR_API_CONFIG` environment variable after loading dotenv config. - For multi-tenant deployments, optionally set `VELOCIRAPTOR_ORG_ID` to choose a default org context. - Set `VELOCIRAPTOR_DEBUG_VQL=1` only when you want raw VQL request logging on stderr for debugging. - Set `ENABLE_DANGEROUS_TOOLS=true` only when you explicitly want to enable raw VQL, quarantine, and remote process-kill tools. - The agent POC defaults to local Ollama summaries. Set `VELOCIRAPTOR_MODEL_PROVIDER=azure`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, and `AZURE_OPENAI_MODEL` when you explicitly want Azure OpenAI summaries.

3. Connect to MCP client of choice

The easiest configuration is to run your venv python directly calling `mcp_velociraptor_bridge.py`. You can either put values directly in the MCP client config:

{
  "mcpServers": {
    "velociraptor": {
      "command": "/path/to/venv/bin/python",
      "env": {
        "VELOCIRAPTOR_API_CONFIG": "/path/to/api_client.yaml",
        "VELOCIRAPTOR_ORG_ID": "O123"
      },
      "args": [
        "/path/to/mcp_velociraptor_bridge.py"
      ]
    }
  }
}

Or point the MCP client at a dotenv file:

{
  "mcpServers": {
    "velociraptor": {
      "command": "/path/to/venv/bin/python",
      "env": {
        "VELOCIRAPTOR_ENV_FILE": "/path/to/mcp-velociraptor/.env"
      },
      "args": [
        "/path/to/mcp_velociraptor_bridge.py"
      ]
    }
  }
}

Config precedence is: direct environment values from the MCP client or shell, then `VELOCIRAPTOR_ENV_FILE` if set, then repo-local `.env`, then fallback paths such as `./api_client.yaml` and `~/.config/api_client.yaml`.

The separate agent proof-of-concept now lives under `agent_poc/`. It now includes an engagement manager that fans out to isolated, dynamically allowlisted analysts in parallel. The `engagement` profile runs bounded process, network, persistence, execution, user-activity, and system-inventory roles; `deep` also opts into heavier filesystem and security roles. Evidence collection is deterministic and synthesis is model-only per role. It supports local Ollama summaries by default and opt-in Azure OpenAI API summaries via environment configuration. Azure OpenAI mode sends collected evidence bundles to the configured Azure API account for summarization. See `agent_poc/README.md` for agent-specific usage and automation examples, including verbose collection progress output with artifact names and row counts.

4. Tool Response Format

MCP tool responses are emitted as JSON text envelopes so stdio clients do not need to parse Python `repr()` output:

{"ok": true, "data": {...}}

or

{"ok": false, "error": "message"}

`collect_artifact` and `hunt_across_fleet` accept `parameters` as a structured JSON object with scalar values or lists of scalar values, for example `{"PathRegex": ".*", "Targets": ["_BasicCollection"]}`. Legacy compatibility

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 157 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Velociraptor MCP
  2. Velociraptor MCP is a POC Model Context Protocol bridge for exposing LLMs to MCP clients.
  3. Initial version has several Windows orientated triage tools deployed. Best use is querying usecase to target machine name.
  4. e.g
  5. `can you give me all network connections on MACHINENAME and look for suspicious processes?`
  6. `can you tell me which artifacts target the USN journal`
  7. ## Installation
  8. ### 1. Setup an API account
  9. https://docs.velociraptor.app/docs/server_automation/server_api/
  10. Generate an api config file:
  11. `velociraptor --config /etc/velociraptor/server.config.yaml config api_client --name api --role administrator,api api_client.yaml`
  12. ### 2. Clone mcp-velociraptor repo and test API
  13. - Copy `api_client.yaml` to the repo root, or keep it anywhere local and set `VELOCIRAPTOR_API_CONFIG=/path/to/api_client.yaml`.
  14. - Copy `example.env` to `.env` for local development, then set `VELOCIRAPTOR_API_CONFIG` to your real `api_client.yaml` path. The bridge, smoke script, and agent load dotenv config automatically without overriding variables already supplied by your shell or MCP client.
  15. - `api_client.yaml` is gitignored and should not be committed.
  16. - Run `.venv/bin/python test_api.py` to confirm the API works when `.env` is configured, or use `VELOCIRAPTOR_API_CONFIG=/path/to/api_client.yaml .venv/bin/python test_api.py` to override it for a single run.
  17. - The MCP bridge reads the same `VELOCIRAPTOR_API_CONFIG` environment variable after loading dotenv config.
  18. - For multi-tenant deployments, optionally set `VELOCIRAPTOR_ORG_ID` to choose a default org context.
  19. - Set `VELOCIRAPTOR_DEBUG_VQL=1` only when you want raw VQL request logging on stderr for debugging.
  20. - Set `ENABLE_DANGEROUS_TOOLS=true` only when you explicitly want to enable raw VQL, quarantine, and remote process-kill tools.
  21. - The agent POC defaults to local Ollama summaries. Set `VELOCIRAPTOR_MODEL_PROVIDER=azure`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, and `AZURE_OPENAI_MODEL` when you explicitly want Azure OpenAI summaries.
  22. ### 3. Connect to MCP client of choice
  23. The easiest configuration is to run your venv python directly calling
  24. `mcp_velociraptor_bridge.py`. You can either put values directly in the MCP
  25. client config:
  26. ```json
  27. {
  28. "mcpServers": {
  29. "velociraptor": {
  30. "command": "/path/to/venv/bin/python",
  31. "env": {
  32. "VELOCIRAPTOR_API_CONFIG": "/path/to/api_client.yaml",
  33. "VELOCIRAPTOR_ORG_ID": "O123"
  34. },
  35. "args": [
  36. "/path/to/mcp_velociraptor_bridge.py"
  37. ]
  38. }
  39. }
  40. }
  41. ```
  42. Or point the MCP client at a dotenv file:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "velociraptor": {
  47. "command": "/path/to/venv/bin/python",
  48. "env": {
  49. "VELOCIRAPTOR_ENV_FILE": "/path/to/mcp-velociraptor/.env"
  50. },
  51. "args": [
  52. "/path/to/mcp_velociraptor_bridge.py"
  53. ]
  54. }
  55. }
  56. }
  57. ```
  58. Config precedence is: direct environment values from the MCP client or shell,
  59. then `VELOCIRAPTOR_ENV_FILE` if set, then repo-local `.env`, then fallback
  60. paths such as `./api_client.yaml` and `~/.config/api_client.yaml`.
  61. The separate agent proof-of-concept now lives under `agent_poc/`. It now
  62. includes an engagement manager that fans out to isolated, dynamically
  63. allowlisted analysts in parallel. The `engagement` profile runs bounded
  64. process, network, persistence, execution, user-activity, and system-inventory
  65. roles; `deep` also opts into heavier filesystem and security roles. Evidence
  66. collection is deterministic and synthesis is model-only per role. It supports local
  67. Ollama summaries by default and opt-in Azure OpenAI API summaries via
  68. environment configuration. Azure OpenAI mode sends collected evidence bundles
  69. to the configured Azure API account for summarization. See
  70. `agent_poc/README.md` for agent-specific usage and automation examples,
  71. including verbose collection progress output with artifact names and row counts.
  72. ### 4. Tool Response Format
  73. MCP tool responses are emitted as JSON text envelopes so stdio clients do not
  74. need to parse Python `repr()` output:
  75. ```json
  76. {"ok": true, "data": {...}}
  77. ```
  78. or
  79. ```json
  80. {"ok": false, "error": "message"}
  81. ```
  82. `collect_artifact` and `hunt_across_fleet` accept `parameters` as a structured
  83. JSON object with scalar values or lists of scalar values, for example
  84. `{"PathRegex": ".*", "Targets": ["_BasicCollection"]}`. Legacy compatibility
  85. input can be supplied via `legacy_parameters` with simple scalar assignments or
  86. list literals such as `PathRegex='.*',Targets=['_BasicCollection']`; raw VQL
  87. fragments are no longer passed through.
  88. Parameterized hunts are validated against Velociraptor's compiled collector
  89. args; if the requested artifact env does not land, the hunt is stopped and the
  90. tool returns an error.
  91. `collect_forensic_triage` wraps `Windows.Triage.Targets` with
  92. `Targets='["_BasicCollection"]'` and a collection timeout of `2400` seconds.
  93. ### 5. Tool Inventory
  94. The bridge now exposes the original Windows/Linux triage tools plus expanded
  95. fleet, Linux, macOS, Windows, YARA, and response helpers:
  96. - Fleet: `list_orgs`, `client_info`, `list_clients`, `hunt_across_fleet`, `get_hunt_results_tool`, `run_vql`.
  97. - Artifact discovery: `list_windows_artifacts`, `list_linux_artifacts`, and `list_macos_artifacts` accept `name_regex` filters and `include_parameter_details=true` for full live parameter metadata from `artifact_definitions()`.
  98. - Linux: process, group, mount, network, users, crontab, services, SSH keys/logins, shell history, last login, ARP cache, journal search, file finder, and YARA process scanning.
  99. - macOS: process, users, network, LaunchAgents/Daemons, login items, shell history, browser history, quarantine events, TCC database, file finder, and artifact discovery.
  100. - Windows: process, network, scheduled tasks, services, RecentDocs, Shellbags, USB/mount evidence, execution traces, MFT, USN, SRUM, EVTX, PowerShell, autoruns, WMI persistence, RDP, DNS cache, Recycle Bin, browser history, memory/malfind/mutant checks, shadow copies, timestomp checks, and file/YARA hunting with optional hash calculation.
  101. - Generic response/collection: `collect_artifact`, `get_collection_results`, `collect_forensic_triage`, `collect_file`, `quarantine_host`, `unquarantine_host`, and `kill_process`.
  102. Thanks to [@snoe-findley](https://github.com/snoe-findley) for sharing a fork
  103. that expanded available tools and some of the newer cross-platform additions.
  104. ![image](https://github.com/user-attachments/assets/3e810f03-ca74-4757-b5dc-89d4e8f8aef6)
  105. ### 6. Caveats
  106. Due to the nature of DFIR, results depend on amount of data returned, model use and context window.
  107. I have included a function to find artifacts and dynamically create collections but had mixed results.
  108. I have been pleasantly surprised with some results and disappointed when running other collections that cause lots of rows.
  109. Check licencing - Anthropic's DPA is only tied to their Commercial Terms, which means that for
  110. client/production endpoint data you would need commercial licencing to leverage this MCP. Other
  111. MCP clients work just fine.
  112. Please let me know how you go and feel free to add PR!
  113. `can you give me all network connections on MACHINENAME and look for suspicious processes?`
  114. <img alt="image" src="https://github.com/user-attachments/assets/cc19ccde-f8fa-40d5-8b4d-82215777dc6b" />
  115. <img alt="image" src="https://github.com/user-attachments/assets/734ce6d0-6c66-49cf-a0f7-8236f7435be3" />
  116. <img alt="image" src="https://github.com/user-attachments/assets/b6593321-1089-4f00-8011-5ef08cf80d88" />
  117. `can you tell me which artifacts target the USN journal`
  118. <img alt="image" src="https://github.com/user-attachments/assets/b9f93b1c-4a08-437d-b25a-ff82bdd2ab8c" />

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.