VictoriaMetrics MCP Server

!License !Slack !X !Reddit

The implementation of Model Context Protocol (MCP) server for VictoriaMetrics.

This provides access to your VictoriaMetrics instance and seamless integration with VictoriaMetrics APIs and documentation. It can give you a comprehensive interface for monitoring, observability, and debugging tasks related to your VictoriaMetrics instances, enable advanced automation and interaction capabilities for engineers and tools.

Features

This MCP server allows you to use almost all read-only APIs of VictoriaMetrics, i.e. all functions available in VMUI:

• Querying metrics and exploring data (even drawing graphs if your client supports it)
• Listing and exporting available metrics, labels, labels values and entire series
• Analyzing and testing your alerting and recording rules and alerts
• Showing parameters of your VictoriaMetrics instance
• Exploring cardinality of your data and metrics usage statistics
• Analyzing, tracing, prettifying and explaining your queries
• Debugging your relabeling rules, downsampling and retention policy configurations
• Integration with VictoriaMetrics Cloud
• UI with setup instrinctions and tools inspection on the root endpoint (only in Streamable HTTP mode)

!image

More details about the exact available tools and prompts can be found in the Usage section.

You can combine functionality of tools, docs search in your prompts and invent great usage scenarios for your VictoriaMetrics instance. Just check the Dialog example section to see how it can work. And please note the fact that the quality of the MCP Server and its responses depends very much on the capabilities of your client and the quality of the model you are using.

You can also combine the MCP server with other observability or doc search related MCP Servers and get even more powerful results.

Try without installation

There is a publicly available instance of the VictoriaMetrics MCP Server that you can use to test the features without installing it:

https://play-mcp.victoriametrics.com/mcp

Attention! This URL is not supposed to be opened in a browser, it is intended to be used in MCP clients.

It's available in Streamable HTTP mode and configured to work with Public VictoriaMetrics Playground.

Here is example of configuration for Claude Desktop:

!image

Requirements

• VictoriaMetrics or VictoriaMetrics Cloud instance (single-node or cluster)
• Go 1.26 or higher (if you want to build from source)

Installation

Binaries

Just download the latest release from Releases page and put it to your PATH.

Example for Linux x86_64 (note that other architectures and platforms are also available):

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

Docker

You can run VictoriaMetrics MCP Server using Docker.

This is the easiest way to get started without needing to install Go or build from source.

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

You should replace environment variables with your own parameters.

Note that the MCP_SERVER_MODE=http flag is used to enable Streamable HTTP mode. More details about server modes can be found in the Configuration section.

See available docker images in github registry.

Also see Using Docker instead of binary section for more details about using Docker with MCP server with clients in stdio mode.

Source Code

For building binary from source code you can use the following approach:

• Clone repo:

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

• Build binary from cloned source code:

make build
  # after that you can find binary mcp-victoriametrics and copy this file to your PATH or run inplace

• Build image from cloned source code:

docker build -t mcp-victoriametrics .
  # after that you can use docker image mcp-victoriametrics for running or pushing

Helm

Check out VictoriaMetrics MCP Server Helm chart documentation for more details about installation using Helm.

Configuration

MCP Server for VictoriaMetrics is configured via environment variables:

| Variable | Description | Required | Default | Allowed values | |------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|---------------------------------------------------------------------------------------------------|------------------------| | VM_INSTANCE_ENTRYPOINT / VMC_API_KEY | URL to VictoriaMetrics instance (it should be root / URL of vmsingle or vmselect) | Yes (if you don't use VMC_API_KEY) | - | - | | VM_INSTANCE_TYPE | Type of VictoriaMetrics instance | Yes (if you don't use `VMC_API_KEY) | - | single, cluster | | VM_INSTANCE_BEARER_TOKEN | Authentication token for VictoriaMetrics API | No | - | - | | VM_INSTANCE_HEADERS | Custom HTTP headers to send with requests (comma-separated key=value pairs) | No | - | - | | MCP_PASSTHROUGH_HEADERS | HTTP header names to forward from incoming MCP requests to VictoriaMetrics (comma-separated list). Overrides VM_INSTANCE_HEADERS on collision. Only applies in sse/http modes. | No | - | - | | VM_DEFAULT_TENANT_ID | Default tenant ID for cluster mode. Format: accountID or accountID:projectID (32-bit integers). See VictoriaMetrics cluster docs | No | 0 | - | | VMC_API_KEY | API key from VictoriaMetrics Cloud Console | No | - | - | | MCP_SERVER_MODE | Server operation mode. See Modes for details. | No | stdio | stdio, sse, http | | 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 | 'export,flags,metric_relabel_debug,downsampling_filters_debug,retention_filters_debug,test_rules' | - | | MCP_DISABLE_RESOURCES | Disable all resources (documentation tool will continue to work) | No | false | false, true | | MCP_HEARTBEAT_INTERVAL | Defines the heartbeat interval for the streamable-http protocol.
It means the MCP server will send a heartbeat to the client through the GET connection,
to keep the connection alive from being closed by the network infrastructure (e.g. gateways) | No | 30s | - | | MCP_LOG_FORMAT | Log output format | No | text | text, json | | MCP_LOG_LEVEL | Minimum log level | No | info | debug, info, warn, error |

• Using VM_INSTANCE_ENTRYPOINT + VM_INSTANCE_TYPE + VM_INSTANCE_BEARER_TOKEN (optional) environment variables to connect to any single-node or cluster instance of VictoriaMetrics.
• Using VMC_API_KEY environment variable to work with your VictoriaMetrics Cloud instances.

• stdio - Standard input/output mode, where the server reads commands from standard input and writes responses to standard output. This is the default mode and is suitable for local servers.
• sse - Server-Sent Events. Server will expose the /sse and /message endpoints for SSE connections.
• http - Streamable HTTP. Server will expose the /mcp endpoint for HTTP connections.

# For a single-node instance
export VM_INSTANCE_ENTRYPOINT="http://localhost:8428"
export VM_INSTANCE_TYPE="single"
export VM_INSTANCE_BEARER_TOKEN="your-token"
export MCP_PASSTHROUGH_HEADERS="X-Token,X-Access-Key"
For a cluster
export VM_INSTANCE_ENTRYPOINT="https://play.victoriametrics.com"
export VM_INSTANCE_TYPE="cluster"
export MCP_DISABLED_TOOLS="export,metric_statistics,test_rules" # disable export, statistics and rules unit test tools
For VictoriaMetrics Cloud
export VMC_API_KEY="<you-api-key>"
Server mode
export MCP_SERVER_MODE="sse"
export MCP_LISTEN_ADDR="0.0.0.0:8080"
Custom headers for authentication (e.g., behind a reverse proxy)
Expected syntax is key=value separated by commas
export VM_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

| Endpoint | Description | |----------------------|--------------------------------------------------------------------------------------------------| | / | Landing page with setup help and tool inspection | | /sse + /message | Endpoints for messages in SSE mode (for MCP clients that support SSE) | | /mcp | HTTP endpoint for streaming messages in HTTP mode (for MCP clients that support Streamable HTTP) | | /metrics | Metrics in Prometheus format for monitoring the MCP server | | /health/liveness | Liveness check endpoint to ensure the server is running | | /health/readiness | Readiness check endpoint to ensure the server is ready to accept requests |

Add this to your Claude Desktop claude_desktop_config.json file (you can find it if open Settings -> Developer -> Edit config):

{
  "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>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

{
  "mcpServers": {
    "victoriametrics": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/mcp"]
    }
  }
}

claude mcp add victoriametrics \
  -e VM_INSTANCE_ENTRYPOINT=<YOUR_VM_INSTANCE> \
  -e VM_INSTANCE_TYPE=<YOUR_VM_INSTANCE_TYPE> \
  -e VM_INSTANCE_BEARER_TOKEN=<YOUR_VM_BEARER_TOKEN> \
  -e VM_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>" \
  -- /path/to/mcp-victoriametrics

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

claude mcp add victoriametrics --transport http http://localhost:8080/mcp

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server and paste the following configuration into your Cursor ~/.cursor/mcp.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>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

{
  "mcpServers": {
    "victoriametrics": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Codex CLI and the IDE extension use the same MCP configuration file: ~/.codex/config.toml (or .codex/config.toml in a trusted project).

codex mcp add victoriametrics \
  --env VM_INSTANCE_ENTRYPOINT=<YOUR_VM_INSTANCE> \
  --env VM_INSTANCE_TYPE=<YOUR_VM_INSTANCE_TYPE> \
  --env VM_INSTANCE_BEARER_TOKEN=<YOUR_VM_BEARER_TOKEN> \
  --env VM_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>" \
  -- /path/to/mcp-victoriametrics

Or add the following to your Codex ~/.codex/config.toml file:

[mcp_servers.victoriametrics]
command = "/path/to/mcp-victoriametrics"
[mcp_servers.victoriametrics.env]
VM_INSTANCE_ENTRYPOINT = "<YOUR_VM_INSTANCE>"
VM_INSTANCE_TYPE = "<YOUR_VM_INSTANCE_TYPE>"
VM_INSTANCE_BEARER_TOKEN = "<YOUR_VM_BEARER_TOKEN>"
VM_INSTANCE_HEADERS = "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

codex mcp add victoriametrics --url http://localhost:8080/mcp

{
  "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>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

{
  "servers": {
    "victoriametrics": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

"context_servers": {
  "victoriametrics": {
    "command": {
      "path": "/path/to/mcp-victoriametrics",
      "args": [],
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    },
    "settings": {}
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

{
  "context_servers": {
    "victoriametrics": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

• Open Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP).
• Click Add (+)
• Select As JSON
• Put the following to the input field:

{
  "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>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

{
  "mcpServers": {
    "victoriametrics": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

{
  "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>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

{
  "mcpServers": {
    "victoriametrics": {
      "serverUrl": "http://localhost:8080/mcp"
    }
  }
}

Add the following to your Gemini CLI ~/.gemini/settings.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>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

gemini mcp add victoriametrics --transport http http://localhost:8080/mcp

Add the following to your OpenCode config file in ~/.config/opencode/opencode.json:

{
  "mcp": {
    "victoriametrics": {
      "type": "local",
      "command": ["/path/to/mcp-victoriametrics"],
      "enabled": true,
      "environment": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

To connect to a server running in Streamable HTTP mode at http://localhost:8080:

{
  "mcp": {
    "victoriametrics": {
      "type": "remote",
      "url": "http://localhost:8080/mcp"
    }
  }
}

{
  "mcpServers": {
    "victoriametrics": {
      "command": "docker",
        "args": [
          "run",
          "-i", "--rm",
          "-e", "VM_INSTANCE_ENTRYPOINT",
          "-e", "VM_INSTANCE_TYPE",
          "-e", "VM_INSTANCE_BEARER_TOKEN",
          "-e", "VM_INSTANCE_HEADERS",
          "ghcr.io/victoriametrics/mcp-victoriametrics",
        ],
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>",
        "VM_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

Use MCP VictoriaMetrics in the following answers

| Tool | Description | Enabled by default | |------------------------------|--------------------------------------------------------|:------------------:| | active_queries | Active queries | ✅ | | alerts | List of alerts | ✅ | | documentation | Search documentation resources | ✅ | | downsampling_filters_debug | Downsampling filters debugger | ❌ | | explain_query | Explain Query | ✅ | | export | Export time series | ❌ | | flags | List of non-default flags (parameters) | ❌ | | label_values | List of label values | ✅ | | labels | List of label names | ✅ | | metric_relabel_debug | Metric relabel debugger | ❌ | | metric_statistics | Metric statistics | ✅ | | metrics | List of metric names | ✅ | | metrics_metadata | List of metrics metadata (name, type, help and unit) | ✅ | | prettify_query | Prettify Query | ✅ | | query | Instant Query | ✅ | | query_range | Range Query | ✅ | | retention_filters_debug | Retention filters debugger | ❌ | | rules | List of alerting and recording rules | ✅ | | series | List of time series | ✅ | | tenants | List of tenants (cluster mode only) | ✅ | | test_rules | Unit test rules | ❌ | | top_queries | Top queries | ✅ | | tsdb_status | TSDB Stats (information about cardinality of the data) | ✅ |

| Prompt | Description | |---------------------------------------------|---------------------------------------------------------------------------------------| | documentation | Search by VictoriaMetrics documentation or give context for answering questions | | rarely_used_metrics_with_high_cardinality | List of rarely used metrics with high cardinality in the VictoriaMetrics instance API | | unused_metrics | List of unused (never queried) metrics in the VictoriaMetrics instance API |

Additional tools available for VictoriaMetrics Cloud deployments (with VMC_API_KEY parameter). In this mode, tools working with data require the deployment_id parameter.

| Tool | Description | Enabled by default | |-------------------|---------------------------------------------------|:------------------:| | access_tokens | List of deployment access tokens | ✅ | | cloud_providers | List of cloud providers | ✅ | | deployments | List of deployments | ✅ | | regions | List of regions | ✅ | | rule_file | Get rules file content | ✅ | | rule_filenames | List of filenames of alerting and recording rules | ✅ | | tiers | List of tiers | ✅ |

🤖 In your VictoriaMetrics instance, the following tenants are available 0:0 (default tenant), 1:0, 10:0, 100:0

> - System metrics (node_, machine_, etc.),

- Kubernetes metrics (kube_, container_, apiserver_, etc.),

- VictoriaMetrics-specific metrics (vm_, vmagent_, vmalert_, etc.),

- Go runtime metrics (go_),

- Prometheus-related metrics (scrape_, promhttp_),

- Various application metrics (argocd_, alertmanager_).

> - kube_persistentvolumeclaim_deletion_timestamp - This metric provides information about when PersistentVolumeClaims were marked for deletion.

- kube_pod_init_container_status_last_terminated_reason - This metric shows the reason why init containers in pods were last terminated.

1. Look at each metric's name (the __name__ label)

> - The first two test cases show that both kube_persistentvolumeclaim_deletion_timestamp and kube_pod_init_container_status_last_terminated_reason metrics are correctly dropped (resulting labels are empty {}).

- The third test case confirms that other metrics like kube_pod_status_phase are preserved and not affected by our drop rule.

> - In the VMAgent spec, you use inlineRelabelConfig for inline relabeling rules

- The field is called sourceLabels (not source_labels as in Prometheus config)

• tenants to get the list of available tenants
• documentation to get information about functionality and data formats
• metrics to get the list of available metrics
• metric_statistics to get the information about metrics usage
• series to get the time series for debugging
• metric_relabel_debug to debug relabeling rules
• flags to get the information about instance parameters
• downsampling_filters_debug to debug downsampling configuration

The server contains an embedded vector database with VictoriaMetrics documentation and blog posts for the documentation tool. It helps to answer complex questions about VictoriaMetrics without providing all data to LLM. This is the main source of resource usage. To reduce it, add documentation to MCP_DISABLED_TOOLS environment variable to completely disable the vector database loading.

You can use MCP_PASSTHROUGH_HEADERS parameter in the MCP Server together with Header-based routing in vmauth to route MCP calls between instances based on HTTP header values from your MCP client config.

• [x] Support "Prettify query" tool (done in v0.0.5)
• [x] Support "Explain query" tool (done in v0.0.6)
• [x] Support CI pipeline for building and pushing multiarch docker images (done in v1.0.0)
• [x] Support tool for unit-testing of alerting and recording rules (done in v0.0.7)
• [x] Support optional integration with VictoriaMetrics Cloud (via API keys) (done in v0.0.9)
• [ ] Add some extra knowledge to server in addition to current documentation tool:

• [ ] Implement multitenant version of MCP (that will support several deployments)
• [ ] Add flags/configs validation tool
• [ ] Support tools for vmagent API
• [ ] Support new vmalert API
• [x] Enabling/disabling tools via configuration (done in v0.0.8`)
• [ ] Tools for Alertmanager APIs #6
• [x] Support for metrics metadata in case of implementation in VictoriaMetrics
• [ ] Support authentication
• [x] Add static index page with description and links to documentation

Mentions

Disclaimer

AI services and agents along with MCP servers like this cannot guarantee the accuracy, completeness and reliability of results. You should double check the results obtained with AI.

The quality of the MCP Server and its responses depends very much on the capabilities of your client and the quality of the model you are using.

Contributing

Contributions to the MCP VictoriaMetrics project are welcome!

Please feel free to submit issues, feature requests, or pull requests.