VictoriaMetrics-mcp-server

Instructions

Implementation Reference

• src/index.js:136-163 (handler)

  Core handler function for vm_query tool: queries VictoriaMetrics /api/v1/query endpoint and returns JSON response.

  async function vmDataQuery(query, step) {
    let urlStr = VM_URL
    if (urlStr === "") {
      urlStr = VM_SELECT_URL
    }
    const url = new URL(urlStr + "/api/v1/query");
    url.searchParams.append("query", query);
    const response = await fetch(url.toString());
    const data = await response.json();
  
    if (data.status === "success") {
      return {
        content: [{
          type: "text",
          text: JSON.stringify(data.data),
        }],
        isError: false
      };
    } else {
      return {
        content: [{
          type: "text",
          text: "range query fail:" + await response.text(),
        }],
        isError: true
      };
    }
  }

• src/index.js:352-355 (handler)

  Dispatch handler in CallToolRequestSchema: calls vmDataQuery with tool arguments for vm_query.

  case "vm_query": {
    const {query, start, end, step} = request.params.arguments;
    return await vmDataQuery(query, start, end, step);
  }

• src/index.js:82-99 (schema)

  Tool definition with input schema: PromQL 'query' required, optional 'time'.

  const VM_QUERY_TOOL = {
    name: "vm_query",
    description: "Query current value of a time series",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "PromQL expression to evaluate",
        },
        time: {
          type: "number",
          description: "Evaluation timestamp in Unix seconds (optional)",
        }
      },
      required: ["query"],
    }
  };

• src/index.js:127-134 (registration)

  Registers vm_query tool (line 130) in VM_TOOLS array used for listing tools.

  const VM_TOOLS = [
    VM_DATA_WRITE_TOOL,
    VM_QUERY_RANGE_TOOL,
    VM_QUERY_TOOL,
    VM_LABELS_TOOL,
    VM_LABEL_VALUES_TOOL,
    VM_PROMETHEUS_WRITE_TOOL
  ];

• src/index.js:341-385 (registration)

  Registers the call tool request handler with switch dispatch including vm_query case.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      switch (request.params.name) {
        case "vm_data_write": {
          const {metric, values, timestamps} = request.params.arguments;
          return await vmMetricsDataWrite(metric, values, timestamps);
        }
        case "vm_query_range": {
          const {query, start, end, step} = request.params.arguments;
          return await vmDataRangeQuery(query, start, end, step);
        }
        case "vm_query": {
          const {query, start, end, step} = request.params.arguments;
          return await vmDataQuery(query, start, end, step);
        }
        case "vm_labels": {
          return await vmLabels();
        }
        case "vm_label_values": {
          const {label} = request.params.arguments;
          return await vmLabelValues(label);
        }
        case "vm_prometheus_write": {
          const {data} = request.params.arguments;
          return await vmPrometheusWrite(data);
        }
        default:
          return {
            content: [{
              type: "text",
              text: `Unknown tool: ${request.params.name}`
            }],
            isError: true
          };
      }
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  });