victoriametrics-mcp

An MCP server that lets an LLM agent query VictoriaMetrics (PromQL/MetricsQL) and VictoriaLogs (LogsQL) over stdio.

Because it speaks the Prometheus HTTP API, it also works against Prometheus itself for the vm_* metric tools.

Built with Bun and TypeScript; compiles to a single self-contained binary with no runtime dependency.

Why another exporter-ish tool

Raw Prometheus JSON is a poor fit for a model's context window: a single range query easily returns tens of thousands of tokens of repeated label sets and float noise. Every tool here returns compact text instead:

• series are rendered as metric{label="value"}, sorted and deduplicated;
• values are rounded to 4 significant digits;
• timestamps are second-precision UTC (2026-08-13T10:30:00Z);
• range results are summarised (min/max/avg/last) and evenly subsampled;
• results are bounded by explicit limit / max_series / max_points args, and truncation is always announced so the model knows to raise the limit;
• log lines drop ANSI colour codes and Docker/Vector bookkeeping fields.

Install

bun install          # never npm
bun run build        # -> dist/victoriametrics-mcp

Or with just: just build.

Configuration

Everything is read from the environment, so one binary serves any deployment.

Variable	Default	Meaning
VM_URL	http://127.0.0.1:8428	VictoriaMetrics (or Prometheus) base URL
VL_URL	http://127.0.0.1:9428	VictoriaLogs base URL
VM_TIMEOUT_MS	30000	Per-request timeout, both backends
VM_BEARER_TOKEN / VL_BEARER_TOKEN	—	Sent as Authorization: Bearer …
VM_USER + VM_PASSWORD	—	HTTP basic auth (same for VL_*)

If a bearer token is set it takes precedence over basic auth.

Registering with a client

Claude Code, user scope:

claude mcp add --scope user victoriametrics -- /path/to/dist/victoriametrics-mcp

Any other MCP client, via mcpServers config:

{
  "mcpServers": {
    "victoriametrics": {
      "command": "/path/to/dist/victoriametrics-mcp",
      "env": { "VM_URL": "http://127.0.0.1:8428" }
    }
  }
}

Tools

Metrics — VictoriaMetrics

Tool	Purpose	Key arguments
vm_query	Instant PromQL query — the current value per series	query, time, limit
vm_query_range	Range query — how a metric evolved	query, start, end, step, max_series, max_points
vm_series	Discover which series exist	match[], start, end, limit
vm_label_values	List values of a label (__name__ lists metric names)	label, match[], start, end, limit
vm_targets	Scrape target health — job, instance, health, last error	only_unhealthy

Logs — VictoriaLogs

Tool	Purpose	Key arguments
vl_query	Run a LogsQL query	query, limit, max_message_chars

Time arguments

Every time / start / end argument accepts:

• now (or empty),
• a relative offset: -12h, -30m, -7d, -2w,
• an epoch in seconds: 1786609796,
• an RFC3339 timestamp: 2026-08-13T10:30:00Z.

step accepts a duration (30s, 1m, 1h) or bare seconds. When omitted, vm_query_range picks a step yielding roughly 60 points over the range.

Example output

vm_query with query=up:

10 series at 2026-08-13T08:33:49Z
up{cluster="mini-box",instance="traefik:8082",job="traefik"} = 1
up{cluster="mini-box",instance="localhost:8428",job="victoriametrics"} = 1
…

vm_query_range with query=sum(rate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance):

range -2h → now, step 120s

2 series

{instance="mini-box"}
  min=11.01 max=11.64 avg=11.56 last=11.34 (5 of 61 points shown)
  2026-08-13T06:34:00Z  11.64
  …
  2026-08-13T08:34:00Z  11.34

vm_targets:

10 targets, 1 not up
DOWN    postgres-exporter / arcle_postgres-exporter:9187
UP      traefik / traefik:8082
…

Development

just dev          # run from source over stdio
just typecheck    # tsc --noEmit
just test         # unit tests (bun test)
just smoke        # build, then drive the binary with real MCP JSON-RPC

just smoke performs a genuine end-to-end check: it starts the compiled binary, sends initialize, notifications/initialized, tools/list and two tools/call requests on stdin, and prints the JSON-RPC replies. It needs a reachable VM_URL.

License

MIT