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.

Related MCP server: Proms MCP Server

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.

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

Logs — VictoriaLogs

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