VictoriaMetrics MCP server

VictoriaMetrics MCP Server is a powerful implementation of the Model Context Protocol that provides AI assistants with access to your VictoriaMetrics monitoring data. It enables seamless integration with VictoriaMetrics APIs and documentation, allowing for comprehensive monitoring, observability, and debugging through natural language interactions.

Installation Options

Using Go

go install github.com/VictoriaMetrics-Community/mcp-victoriametrics/cmd/mcp-victoriametrics@latest

Using Prebuilt Binaries

latest=$(curl -s https://api.github.com/repos/VictoriaMetrics-Community/mcp-victoriametrics/releases/latest | grep 'tag_name' | cut -d\" -f4)
wget https://github.com/VictoriaMetrics-Community/mcp-victoriametrics/releases/download/$latest/mcp-victoriametrics_Linux_x86_64.tar.gz
tar axvf mcp-victoriametrics_Linux_x86_64.tar.gz

Using Docker

docker run -d --name mcp-victoriametrics \
  -e MCP_SERVER_MODE=sse \
  -e VM_INSTANCE_ENTRYPOINT=https://play.victoriametrics.com \
  -e VM_INSTANCE_TYPE=cluster \
  ghcr.io/victoriametrics-community/mcp-victoriametrics

Using Smithery

# List supported MCP clients
npx -y @smithery/cli list clients

# Install for your client
npx -y @smithery/cli install @VictoriaMetrics-Community/mcp-victoriametrics --client <YOUR-CLIENT-NAME>

Configuration

The server is configured via environment variables:

Variable	Description	Required	Default
VM_INSTANCE_ENTRYPOINT	URL to VictoriaMetrics instance (root URL of vmsingle or vmselect)	Yes (if not using VMC_API_KEY)	-
VM_INSTANCE_TYPE	Type of VictoriaMetrics instance (single or cluster)	Yes (if not using VMC_API_KEY)	-
VM_INSTANCE_BEARER_TOKEN	Authentication token for VictoriaMetrics API	No	-
VMC_API_KEY	API key from VictoriaMetrics Cloud	No	-
MCP_SERVER_MODE	Server operation mode (stdio, sse, http)	No	stdio
MCP_LISTEN_ADDR	Address for SSE or HTTP server to listen on	No	localhost:8080
MCP_DISABLED_TOOLS	Comma-separated list of tools to disable	No	-

Client Setup Examples

Claude Desktop

Add to your claude_desktop_config.json file:

{
  "mcpServers": {
    "victoriametrics": {
      "command": "/path/to/mcp-victoriametrics",
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
      }
    }
  }
}

Visual Studio Code

Add to your VS Code MCP config file:

{
  "servers": {
    "victoriametrics": {
      "type": "stdio",
      "command": "/path/to/mcp-victoriametrics",
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
      }
    }
  }
}

Available Tools

MCP VictoriaMetrics provides numerous tools for interacting with your VictoriaMetrics instance:

Core Query Tools

• query - Execute instant PromQL/MetricsQL queries
• query_range - Execute range PromQL/MetricsQL queries over a time period
• metrics - List available metrics
• labels - List available label names
• label_values - List values for a specific label
• series - List available time series

Diagnostic & Analytical Tools

• flags - View non-default flags of the VictoriaMetrics instance
• metric_statistics - Get metrics usage statistics
• active_queries - View currently executing queries
• top_queries - View most frequent or slowest queries
• tsdb_status - View TSDB cardinality statistics

Debug & Development Tools

• metric_relabel_debug - Debug Prometheus-compatible relabeling rules
• downsampling_filters_debug - Debug downsampling configuration
• retention_filters_debug - Debug retention filters configuration
• prettify_query - Prettify and format PromQL/MetricsQL queries
• explain_query - Parse and explain PromQL/MetricsQL queries
• test_rules - Unit-test alerting and recording rules

Additional Tools

• export - Export raw time series data to JSON or CSV
• rules - View alerting and recording rules
• alerts - View current alerts (firing and pending)
• tenants - List available tenants in multi-tenant cluster setup
• documentation - Search in embedded VictoriaMetrics documentation

Usage Tips

To start using the MCP server with your client, you can begin with:

Use MCP VictoriaMetrics in the following answers

Example use cases:

• Query metrics and explore data
• List and export available metrics and time series
• Analyze and test alerting rules
• Explore cardinality and metrics usage statistics
• Debug relabeling rules and downsampling configurations

For advanced users, combining multiple tools in a single interaction can provide comprehensive insights into your monitoring environment.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "victoriametrics" '{"command":"/path/to/mcp-victoriametrics","env":{"VM_INSTANCE_ENTRYPOINT":"<YOUR_VM_INSTANCE>","VM_INSTANCE_TYPE":"<YOUR_VM_INSTANCE_TYPE>","VM_INSTANCE_BEARER_TOKEN":"<YOUR_VM_BEARER_TOKEN>"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "victoriametrics": {
            "command": "/path/to/mcp-victoriametrics",
            "env": {
                "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
                "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
                "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "victoriametrics": {
            "command": "/path/to/mcp-victoriametrics",
            "env": {
                "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
                "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
                "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect