VictoriaMetrics

This VictoriaMetrics MCP Server exposes a set of capabilities to interact with a VictoriaMetrics backend directly from the MCP ecosystem. It provides a collection of tools to write data, import Prometheus-formatted data, and run on-demand PromQL queries against your VictoriaMetrics instance. The available tools include: vm_data_write for writing metric data with tags, values, and timestamps; vm_prometheus_write to ingest data in Prometheus exposition format; vm_query_range to query a range of time series data with PromQL expressions; vm_query to evaluate a single PromQL expression at a given time; vm_labels to retrieve all unique label names; and vm_label_values to fetch all values for a given label. To use them, you typically point the server at your VictoriaMetrics deployment via the VM_URL, and optionally configure VM_SELECT_URL and VM_INSERT_URL for selective routing or insert-specific endpoints. Once deployed, you can call these endpoints through the MCP framework to push data, run queries, or retrieve metadata from VictoriaMetrics. This setup is especially useful for integrating metrics collection into automated workflows and chat-based or agent-assisted querying pipelines.

Prerequisites:

• Node.js (LTS version) and npm installed on your system
• Basic familiarity with npx and MCP workflows

Installation steps:

1. Ensure Node.js and npm are installed. Verify with: node -v npm -v

2. Install and run the VictoriaMetrics MCP Server via npx (as shown in the repository): npx -y @yincongcyincong/victoriametrics-mcp-server

3. Configure environment variables for your VictoriaMetrics instance:

   • VM_URL: URL to your VictoriaMetrics read/write endpoint (e.g., http://localhost:8428)
   • VM_SELECT_URL: optional selector endpoint if you route queries selectively
   • VM_INSERT_URL: optional insert endpoint if you separate insert traffic

4. If you are using Smithery for automated setup, you can follow the Smithery-guided installation command provided in the README to install the MCP server automatically via Smithery: npx -y @smithery/cli install @yincongcyincong/victoriametrics-mcp-server --client claude

5. Start integrating by invoking the provided tools (vm_data_write, vm_prometheus_write, vm_query_range, vm_query, vm_labels, vm_label_values) once the MCP server is running and the VM_URL is reachable.

Tips and caveats:

• Ensure your VictoriaMetrics instance is reachable from the MCP server host; firewall rules or network ACLs may block VM_URL, VM_SELECT_URL, or VM_INSERT_URL.
• When using vm_query_range, only the query field is required; start, end, and step are optional. Provide them as needed to optimize range queries.
• If you use Prometheus format data with vm_prometheus_write, ensure the data adheres to Prometheus exposition format for correct ingestion.
• The MCP server relies on the VM_URL to interact with VictoriaMetrics; if you see authentication or access errors, verify network access and any required credentials by VictoriaMetrics.
• If you need to customize routing, you can configure VM_SELECT_URL and VM_INSERT_URL to point to specific endpoints or proxies.
• For debugging, the Inspector (as shown in the README) can help validate the environment and endpoints: npx @modelcontextprotocol/inspector -e VM_URL=http://127.0.0.1:8428 node src/index.js