VI
OfficialProductivityData Analytics

VictoriaMetrics MCP Server APIs, Monitoring, Documentation

Monitor and debug VictoriaMetrics instances with MCP server APIs, documentation and observability tools for seamless integration and troubleshooting.

View on GitHub
Quick Install
npx -y @VictoriaMetrics-Community/mcp-victoriametrics

Overview

The VictoriaMetrics MCP Server provides a lightweight HTTP API and observability layer that helps you monitor, inspect, and debug VictoriaMetrics instances. It acts as a diagnostics and control plane for VictoriaMetrics deployments, exposing health, metadata, metrics, and debugging endpoints that can be integrated with Prometheus, Grafana, CI/CD and automation tooling.

This server is useful when you need a standardized, machine-readable way to introspect VictoriaMetrics clusters, troubleshoot ingestion or query issues, and collect runtime telemetry (metrics, logs, profiling). It simplifies common operational tasks—like checking instance health, listing connected targets, or gathering pprof traces—without having to run ad-hoc scripts against each VM node.

Features

  • HTTP REST APIs to query instance status, configuration and topology
  • Prometheus metrics endpoint suitable for scraping
  • Health and readiness probes for orchestration systems (Kubernetes)
  • Basic debug endpoints (e.g., logs, runtime profiling) for root-cause analysis
  • Configuration via file and CLI flags for easy automation
  • Lightweight: intended to be run alongside VictoriaMetrics or as a centralized gatekeeper
  • GitHub repository with source code for customization and contribution

Installation / Configuration

Prerequisites: Go 1.18+ (for building from source) or Docker.

Clone repository:

git clone https://github.com/VictoriaMetrics-Community/mcp-victoriametrics.git
cd mcp-victoriametrics

Build from source:

# build the server (example Go build invocation)
go build -o mcp-vm ./cmd/mcp-server
# run with defaults
./mcp-vm --help

Run with Docker:

docker run --rm \
  -p 8080:8080 \
  -e VM_ENDPOINT=http://victoriametrics:8428 \
  ghcr.io/victoriametrics-community/mcp-victoriametrics:latest

Example CLI flags / environment variables (typical):

  • –listen-address=:8080 # HTTP listen address
  • –metrics-endpoint=/metrics # Prometheus metrics path
  • –target-vm=http://vm-host:8428 # Target VictoriaMetrics instance to monitor
  • –config-file=/etc/mcp/config.yaml

Example config file (YAML):

listenAddress: ":8080"
metricsPath: "/metrics"
targets:
  - name: "vm-primary"
    url: "http://vm-primary:8428"
  - name: "vm-replica"
    url: "http://vm-replica:8428"
tls:
  enabled: false
  certFile: "/etc/mcp/tls.crt"
  keyFile: "/etc/mcp/tls.key"
basicAuth:
  username: "mcp"
  password: "changeme"

Start server with config file:

./mcp-vm --config-file=/etc/mcp/config.yaml

Available Resources

  • Source code and issues: https://github.com/VictoriaMetrics-Community/mcp-victoriametrics
  • Prometheus scrape target: /metrics (exposes instrumented metrics from the MCP server)
  • Health endpoints: /health, /ready (for Kubernetes liveness/readiness probes)
  • Diagnostics (examples): /api/instances, /api/instances/{id}/status, /api/instances/{id}/pprof
  • Documentation and contribution guidelines: check the GitHub repository README and docs directory

Note: Exact endpoint paths may vary by release — check the built-in –help or the repository docs for the deployed version.

Use Cases

  1. Quick health checks (Kubernetes probes)

    • Configure liveness and readiness probes to call the MCP server:
    readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

  2. Scrape MCP metrics with Prometheus

    • Add MCP server to Prometheus scrape targets:
    scrape_configs:
  - job_name: 'mcp-victoriametrics'
    static_configs:
      - targets: ['mcp.example.local:8080']
    metrics_path: /metrics

  3. List and inspect instances

    • Retrieve registered VictoriaMetrics instances:
    curl -sS http://localhost:8080/api/instances | jq .
    • Get status for a specific instance:
    curl -sS http://localhost:8080/api/instances/vm-primary/status | jq .

  4. Collect a CPU profile for troubleshooting long queries

    curl -sS http://localhost:8080/api/instances/vm-primary/pprof?seconds=30 -o vm_cpu_profile.pb
# Analyze with go tool pprof
go tool pprof vm_cpu_profile.pb

  5. Debug remote_write / ingestion spikes

    • Use instance status and ingestion-related metrics exposed by MCP to correlate spikes in write latency with network or disk metrics, then export targeted traces or logs.

Monitoring & Troubleshooting Tips

  • Always scrape /metrics from the MCP server itself; it provides telemetry about connectivity to VictoriaMetrics targets and internal error rates.
  • Tie MCP metrics to Grafana dashboards to visualize historical trends (ingestion latency, connection errors, scrape durations).
  • When collecting pprof or logs, prefer short durations (10–60s) to limit
Tags:data-analyticsproductivity