Velociraptor MCP Server

A containerized Model Context Protocol server that exposes a Velociraptor deployment to MCP-compatible clients (Claude, IDE agents, etc.). It connects to Velociraptor's gRPC API over mutual TLS and surfaces both a general-purpose VQL tool and focused DFIR workflow tools.

Tools

Tool	Purpose	Read-only
velociraptor_run_vql	Run any VQL query (full API power)	No*
velociraptor_list_clients	Search enrolled endpoints by host/label	Yes
velociraptor_get_client	Full metadata for one client	Yes
velociraptor_list_hunts	List hunts, newest first	Yes
velociraptor_create_hunt	Create a fleet-wide hunt	No
velociraptor_get_hunt_results	Read rows collected by a hunt	Yes
velociraptor_collect_artifact	Collect artifact(s) from one client	No
velociraptor_get_flow_results	Read results of a completed collection	Yes

* VQL is usually read-only, but it can also perform actions, so the tool isn't marked read-only.

1. Generate an API config on your Velociraptor server

The container authenticates with an api_client config containing mTLS material. Generate one on the Velociraptor server:

velociraptor --config /etc/velociraptor/server.config.yaml \
    config api_client --name mcp --role administrator \
    > ./config/api.config.yaml

Then add the API client's common name to the server's API.access allow-list (the command prints a hint, or configure it in server.config.yaml). Use the least privileged role that meets your needs (e.g. reader if you only need queries).

Place the generated file at ./config/api.config.yaml next to docker-compose.yml. It contains a private key — keep it out of source control (already gitignored).

The config's api_connection_string must be reachable from the container. If Velociraptor runs on the Docker host, use the host's IP (or host.docker.internal on Docker Desktop) rather than 127.0.0.1.

2. Build and run

docker compose up --build -d

This starts the server on http://localhost:8000 using the streamable-HTTP MCP transport. Check logs with docker compose logs -f.

3. Connect a client

Streamable HTTP (default for the container)

Point your MCP client at http://localhost:8000/mcp.

stdio (local, no long-running container)

Some clients launch the server as a subprocess. Run with stdio instead:

{
  "mcpServers": {
    "velociraptor": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_TRANSPORT=stdio",
        "-v", "/abs/path/to/config/api.config.yaml:/config/api.config.yaml:ro",
        "velociraptor-mcp:latest"
      ]
    }
  }
}

Configuration

Env var	Default	Description
VELOCIRAPTOR_API_CONFIG	/config/api.config.yaml	Path to the mounted api_client config
VELOCIRAPTOR_ORG_ID	""	Default org to target ("" = root)
MCP_TRANSPORT	http (image) / stdio (code default)	http or stdio
MCP_HOST	0.0.0.0	Bind host (http only)
MCP_PORT	8000	Bind port (http only)

Example prompts once connected

• "List all Windows hosts seen in the last day."
• "Collect Windows.System.Pslist from C.abc123 and show me the results."
• "Start a hunt collecting Generic.Client.Info across the fleet."
• "Run VQL: SELECT * FROM info()."

Security notes

• The api_client config grants API access at the role you chose — treat it like a credential. Mount it read-only (the compose file does).
• Prefer a narrowly scoped role over administrator where possible.
• The HTTP transport has no built-in auth; bind it to localhost or place it behind a reverse proxy / network policy if exposed beyond the host.
• The server runs as a non-root user inside the container.

Local development (without Docker)

pip install -r requirements.txt
export VELOCIRAPTOR_API_CONFIG=./config/api.config.yaml
export MCP_TRANSPORT=stdio
python server.py