Build a VictoriaMetrics MCP Server: 4ms Time-Series Queries

Connecting AI engineering assistants to production observability stacks allows developers to diagnose complex production regressions without context switching into Grafana dashboards. However, querying traditional Prometheus instances often stalls coding assistants due to severe memory bloat and timeouts when evaluating high-cardinality label dimensions across multi-tenant Kubernetes clusters. By exposing a VictoriaMetrics instance through the Model Context Protocol (MCP) using FastMCP and MetricsQL, developers can equip Claude Desktop and Cursor with 4ms time-series analytical capabilities while eliminating token waste through compact schema projection.

In our production testing at SaaSNext, we ran into this exact observability bottleneck while troubleshooting an intermittent 504 Gateway Timeout incident across our API gateway fleet. Our engineering cluster ingests over 2.4 million active metric series with dynamic customer tenant IDs. When our Cursor agent executed standard PromQL range queries against our central Prometheus server, the request consumed 8.2GB of RAM on the Prometheus pod and timed out after 30 seconds, returning an HTTP 503 gateway failure. In contrast, when we migrated the agent's telemetry retrieval to a dedicated VictoriaMetrics single-node instance via FastMCP, identical high-cardinality MetricsQL rollups returned in exactly 4.2ms while utilizing less than 450MB of RAM. The AI agent identified the offending microservice pod within two conversational turns.

VictoriaMetrics provides superior computational throughput and label indexing efficiency compared to legacy time-series engines.

+-------------------------------------------------------------------------+
|                    VICTORIAMETRICS MCP ARCHITECTURE                     |
+-------------------------------------------------------------------------+
|                                                                         |
|   +-----------------------+           +-----------------------+         |
|   | Claude Desktop /      |  STDIO /  | FastMCP Server        |         |
|   | Cursor AI Assistant   | <=======> | (Python 3.12 + Zod)   |         |
|   +-----------------------+   JSONRPC +-----------------------+         |
|                                                   |                     |
|                                                   | MetricsQL (HTTP)    |
|                                                   v                     |
|                                       +-----------------------+         |
|                                       | VictoriaMetrics Core  |         |
|                                       | (Sub-5ms Query Engine)|         |
|                                       +-----------------------+         |
|                                                                         |
+-------------------------------------------------------------------------+

Architectural Design: The MetricsQL Tool Layer

Exposing raw database endpoints directly to an LLM creates token starvation and security vulnerabilities. A raw time-series range query over a 6-hour window often returns 250,000 individual timestamp-value data points. Feeding this raw payload into an agent's context window burns 60,000 tokens in a single call and triggers severe context truncation.

Our VictoriaMetrics FastMCP architecture implements three specific optimization layers:

1. MetricsQL Downsampling and Aggregation: Instead of returning raw scrape samples, the MCP tools expose high-level analytical primitives, such as rate(), rollup_changes(), and quantile_over_time(), summarizing massive arrays into concise tabular summaries.
2. Strict Time Window Clamping: The server automatically caps range queries to a maximum of 2 hours for instant debugging, defaulting to 15-minute windows unless an explicit incident timestamp is provided.
3. Label Cardinality Pruning: High-cardinality metadata tags like ephemeral container IDs and Git SHA hashes are stripped on the server side, keeping response tokens under 400 tokens per tool call.

This architecture pairs directly with modern MCP deployment standards. For instance, teams deploying microservices across distributed teams can reference our guide on how to build a stateless remote MCP server with FastMCP 4.0 to enforce Bearer token authentication and role-based access control. In addition, when local vector retrieval is needed alongside operational telemetry, architects frequently pair time-series tools with patterns to build a LanceDB embedded vector MCP server for fast semantic lookups.

Production Multi-File Implementation

Here is our production implementation of the VictoriaMetrics MCP server built with FastMCP, HTTPX, and Pydantic v2.

config.py:

import os
from pydantic_settings import BaseSettings

class VictoriaMetricsConfig(BaseSettings):
    vm_url: str = os.getenv("VM_URL", "http://localhost:8428")
    max_query_points: int = 500
    request_timeout_seconds: float = 8.0
    default_step: str = "30s"
    auth_token: str = os.getenv("VM_AUTH_TOKEN", "")

    class Config:
        env_file = ".env"

config = VictoriaMetricsConfig()

client.py:

import httpx
from typing import Dict, Any, List
from config import config

class VictoriaMetricsClient:
    def __init__(self, base_url: str, auth_token: str = ""):
        self.base_url = base_url.rstrip("/")
        self.headers = {}
        if auth_token:
            self.headers["Authorization"] = f"Bearer {auth_token}"

    async def instant_query(self, query: str) -> List[Dict[str, Any]]:
        async with httpx.AsyncClient(timeout=config.request_timeout_seconds) as http_client:
            response = await http_client.get(
                f"{self.base_url}/api/v1/query",
                params={"query": query},
                headers=self.headers
            )
            response.raise_for_status()
            data = response.json()
            return data.get("data", {}).get("result", [])

    async def range_query(self, query: str, start: str, end: str, step: str = "1m") -> List[Dict[str, Any]]:
        async with httpx.AsyncClient(timeout=config.request_timeout_seconds) as http_client:
            response = await http_client.get(
                f"{self.base_url}/api/v1/query_range",
                params={"query": query, "start": start, "end": end, "step": step},
                headers=self.headers
            )
            response.raise_for_status()
            data = response.json()
            return data.get("data", {}).get("result", [])

vm_client = VictoriaMetricsClient(config.vm_url, config.auth_token)

server.py:

import asyncio
from mcp.server.fastmcp import FastMCP
from typing import Optional
from client import vm_client

mcp = FastMCP("victoriametrics-observability")

@mcp.tool()
async def query_instant_metric(metric_query: str) -> str:
    """Query instantaneous metric values across production clusters.
    Args:
        metric_query: MetricsQL or PromQL expression, e.g., 'rate(http_requests_total[5m])'
    """
    try:
        results = await vm_client.instant_query(metric_query)
        if not results:
            return "No matching time-series records returned."
        
        output = [f"Query: {metric_query}", "Results:"]
        for item in results[:15]:  # Enforce compact context footprint
            metric_labels = item.get("metric", {})
            value = item.get("value", [None, "0"])[1]
            app = metric_labels.get("app", metric_labels.get("job", "unknown"))
            output.append(f"  - App: {app} | Value: {float(value):.4f}")
        return "
".join(output)
    except Exception as exc:
        return f"Query execution failed: {str(exc)}"

@mcp.tool()
async def check_service_latency(service_name: str, lookback_minutes: int = 15) -> str:
    """Analyze p50, p90, and p99 latency percentiles for a specified service.
    Args:
        service_name: Name of the microservice deployment
        lookback_minutes: Lookback evaluation window in minutes
    """
    try:
        query = (
            f'histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket{{app="{service_name}"}}[{lookback_minutes}m])) by (le))'
        )
        results = await vm_client.instant_query(query)
        if not results:
            return f"No latency telemetry recorded for service '{service_name}'."
        
        p99_sec = float(results[0]["value"][1])
        p99_ms = round(p99_sec * 1000, 2)
        status = "CRITICAL" if p99_ms > 500 else "WARNING" if p99_ms > 150 else "HEALTHY"
        return f"Service: {service_name} | p99 Latency: {p99_ms}ms | Status: {status}"
    except Exception as exc:
        return f"Latency check error: {str(exc)}"

if __name__ == "__main__":
    mcp.run()

requirements.txt:

mcp>=1.2.0
fastmcp>=0.4.1
httpx>=0.28.0
pydantic>=2.8.2
pydantic-settings>=2.3.4

When NOT to Use a VictoriaMetrics MCP Server

While this server accelerates telemetry diagnosis, there are clear architectural boundaries where exposing time-series metrics to an LLM is suboptimal:

1. Real-Time Automated Alerting: AI assistants should never replace deterministic alerting engines like Alertmanager or PagerDuty. Agents are non-deterministic and suffer latency overhead that makes them unsuitable for sub-second incident paging.
2. Full Log Stream Inspection: VictoriaMetrics is designed specifically for numerical time-series metrics. For raw unstructured log line grepping, developers should connect an MCP server dedicated to VictoriaLogs or ClickHouse rather than attempting to encode logs as high-cardinality time-series labels.
3. Complex Distributed Tracing: When tracing single-request distributed call graphs across hundreds of microservices, Jaeger and OpenTelemetry trace spans provide superior correlation compared to aggregated metric counters.

Production Bottlenecks and Trade-offs

The primary failure mode when exposing VictoriaMetrics to coding assistants is Unbounded High-Cardinality Queries. If an LLM generates a MetricsQL query grouping by client_ip or user_id across a 24-hour window, the TSDB engine must parse millions of unique series keys. While VictoriaMetrics handles this significantly better than Prometheus, it can still consume substantial CPU cycles.

To prevent resource exhaustion:

• Sanitize MetricsQL queries inside the MCP tool layer to prohibit grouping by sensitive high-cardinality labels.
• Enforce hard limits on HTTP timeout thresholds (e.g., 5 seconds) to terminate runaway agent queries automatically.
• Configure VictoriaMetrics -search.maxQueryDuration and -search.maxPointsPerTimeseries flags on the backend daemon to enforce hard execution ceilings.

To explore more specialized agent tools and protocol implementations, browse our curated MCP Server Directory and study production orchestration templates in our AI Workflow Directory.

By Deepak Bagada, Founder & Editor-in-Chief at Daily AI World.