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

* 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

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