MCP Server for VictoriaMetrics. Provides integration with VictoriaMetrics API and documentation
MCP Server for VictoriaMetrics. It provides an integration with the VictoriaMetrics API and access to VictoriaMetrics documentation. The repository is associated with the slug io-github-victoriametrics-community-mcp-victoriametrics and is tagged with topics including ai, mcp, mcp-server, monitoring, observability, victoriametrics, and rag.
🛠️ Key Features
Integration with VictoriaMetrics API
Provides VictoriaMetrics documentation
🚀 Use Cases
Observability and monitoring workflows using VictoriaMetrics
Developer access to VictoriaMetrics documentation alongside API integration
RAG-related use cases associated with the provided rag topic
⚡ Developer Benefits
MCP-based interface for VictoriaMetrics API and documentation
Repository topic alignment with ai and mcp for developer discovery
⚠️ Limitations
Provided data does not specify available tools, endpoints, configuration, or runtime constraints.
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
UI with setup instrinctions and tools inspection on the root endpoint (only in Streamable HTTP mode)
In addition, the MCP server contains embedded up-to-date documentation and is able to search it without online access.
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:
code
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.
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.
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
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_STATELESS
Run the Streamable HTTP server in stateless mode (http mode only). Session IDs are ignored instead of validated, so the server does not reject an Mcp-Session-Id injected by a fronting platform. Required when hosting behind a proxy that manages sessions for you (e.g. AWS Bedrock AgentCore Runtime).
No
false
false, true
MCP_DISABLE_LOCALHOST_PROTECTION
Disable the Streamable HTTP DNS-rebinding guard (http mode only), which otherwise rejects (403) any loopback request whose Host header is not a localhost value. Set true only behind a same-host reverse proxy that forwards over 127.0.0.1 while preserving the original Host header (e.g. AWS Bedrock AgentCore Runtime).
No
false
false, true
MCP_MAX_RESPONSE_SIZE
Maximum size in bytes of a VictoriaMetrics response that a tool reads. A larger response is returned as a tool error instead of being read in full. 0 disables the limit.
No
16777216
-
MCP_INSTRUCTIONS_OVERRIDE
Text that fully replaces the default MCP server instructions sent to clients. Useful for tailoring the server to a particular instance (environment, tenants, naming conventions, etc.)
No
-
-
MCP_AUTH_TOKEN
Bearer token for authenticating incoming MCP requests (only applies in sse/http modes). Public paths (/health/*, /metrics, /, static assets) are excluded from authentication.
No
-
-
MCP_LOG_FORMAT
Log output format
No
text
text, json
MCP_LOG_LEVEL
Minimum log level. debug also logs MCP request and result payloads
No
info
debug, info, warn, error
You can use two options to connect to your VictoriaMetrics instance:
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.
Modes
MCP Server supports the following modes of operation (transports):
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.
Hosting http mode behind a reverse proxy (e.g. AWS Bedrock AgentCore Runtime).
A platform that terminates MCP for you and forwards requests to this server over
loopback — injecting its own Mcp-Session-Id and preserving the original (non-localhost)
Host header — needs two toggles, otherwise tool discovery fails (the server crash-loops
on session rejection, or returns 403 from the DNS-rebinding guard): set
MCP_STATELESS=true and MCP_DISABLE_LOCALHOST_PROTECTION=true alongside
MCP_SERVER_MODE=http. Leave both off for direct/local use.
More info about traqnsports you can find in MCP docs:
# For a single-node instanceexport 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 clusterexport 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 Cloudexport VMC_API_KEY="<you-api-key>"# Server modeexport MCP_SERVER_MODE="sse"export MCP_LISTEN_ADDR="0.0.0.0:8080"# Authentication (optional, only for sse/http modes)export MCP_AUTH_TOKEN="your-secret-token"# Custom headers for authentication (e.g., behind a reverse proxy)# Expected syntax is key=value separated by commasexport VM_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
Endpoints
In SSE and HTTP modes the MCP server provides the following endpoints:
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
Setup in clients
Claude Desktop
Add this to your Claude Desktop claude_desktop_config.json file (you can find it if open Settings -> Developer -> Edit config):
After installing and configuring the MCP server, you can start using it with your favorite MCP client.
You can start dialog with AI assistant from the phrase:
code
Use MCP VictoriaMetrics in the following answers
But it's not required, you can just start asking questions and the assistant will automatically use the tools and documentation to provide you with the best answers.
Just take a look into Dialog example section for better understanding what you can do with it.
Tools and prompts
MCP Server provides numerous tools for interacting with your VictoriaMetrics instance and pre-defined prompts for common tasks.
Tools:
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)
✅
Prompts:
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
VictoriaMetrics Cloud
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
✅
Dialog example
Here is an example of a real dialog with the Assistant using the MCP Server with Claude Desktop, configured to work with the public playground instance. It shows how the server can help in practice.
👤 You: What tenants are available in my VM?
🤖 In your VictoriaMetrics instance, the following tenants are available 0:0 (default tenant), 1:0, 10:0, 100:0
👤 You: From now on, please use only default tenant
🤖 I understand. From now on, I'll use only the default tenant (0:0) for all operations with your VictoriaMetrics instance.
👤 You: Which metrics do we have?
🤖 There are many metrics available in your VictoriaMetrics instance. The list includes metrics from various systems and components, such as:
Various application metrics (argocd_, alertmanager_).
This is a comprehensive list of over 2000 metrics that are available for querying. Is there a specific type of metric you're interested in exploring further?
👤 You: Ok, let's work with kubernetes metrics from now on. Please show me which of these metrics never queried?
🤖 Based on the results, I can see that there are two Kubernetes metrics that have never been queried (query count is 0):
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.
These metrics might be valuable for monitoring and troubleshooting purposes:
The PVC deletion timestamp metric could help track deletion patterns or identify stuck PVCs.
The init container termination reason metric could help identify common failure patterns in your initialization containers.
Would you like me to explain more about what these metrics track or suggest some useful queries to start monitoring them?
👤 You: Yes, please. And also, can you create relabeling rules to stop ingesting these metrics?
🤖 I'll create a relabel configuration to exclude these never-queried metrics from collection. This will help reduce storage and processing overhead. Here's the relabel configuration you can add to your VictoriaMetrics scrape configuration:
Check if it matches either of the specified metrics
Drop the metrics that match, preventing them from being collected and stored
You can add this to your VictoriaMetrics configuration file or to the relevant scrape job configurations in your Prometheus configuration if you're using Prometheus as a scraper for VictoriaMetrics.
If you want to test this relabel configuration before implementing it, you can use the metric relabel debug tool to see how it would affect your metrics.
👤 You: Yes, please debug this relabel config on real time series to see how it would affect my metrics
🤖 Perfect! The relabel config works as expected:
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.
You can confidently add this relabel configuration to your VictoriaMetrics or Prometheus configuration to stop collecting these unused metrics. This will save storage space and reduce processing overhead without affecting your current monitoring capabilities.
👤 You: But i'm using vmagent resource of VictoriaMetrics operator, could you please give me part of specification for my agent with this relabel config?
🤖 You're right, since you're using the VictoriaMetrics Operator and the VMAgent custom resource, the configuration needs to be in the appropriate format for that CR. Here's how you can add the relabel configuration to your VMAgent specification:
yaml
apiVersion:operator.victoriametrics.com/v1beta1kind:VMAgentmetadata:name:your-vmagent-namespec:# ... your existing configuration ...# Add this section to configure global metric relabelinginlineRelabelConfig:-action:dropsourceLabels: ["__name__"]
regex:kube_persistentvolumeclaim_deletion_timestamp|kube_pod_init_container_status_last_terminated_reason# ... rest of your configuration ...
Key points:
In the VMAgent spec, you use inlineRelabelConfig for inline relabeling rules
The field is called sourceLabels (not source_labels as in Prometheus config)
This is a global relabeling that will be applied to all metrics before they're stored
👤 You: I decided not to remove those metrics, but just lower the sample rate for them using Downsampling. What downsampling parameters i have now?
🤖 I can see that you currently have the following downsampling configuration:
code
-downsampling.period="7d:1m,30d:5m,180d:30m"
This means:
Data newer than 7 days is kept at its original resolution
Data between 7-30 days old is downsampled to 1-minute resolution
Data between 30-180 days old is downsampled to 5-minute resolution
Data older than 180 days is downsampled to 30-minute resolution
Now, if you want to add specific downsampling rules for those rarely-queried metrics, you can use the downsampling filters debug tool to test how new rules would work. Let's test a configuration where we apply more aggressive downsampling to those specific metrics:
...getting series and using downsampling filter debugger...
Great! Now our test is working correctly. Based on the current configuration and our testing, here's a suggested downsampling configuration for your VMAgent CR that would apply more aggressive downsampling to those rarely-queried metrics:
yaml
apiVersion:operator.victoriametrics.com/v1beta1kind:VMClustermetadata:name:monitoring-vm-clusterspec:# ... your existing configuration ...# Update the vmstorage section with the new downsampling parametersvmstorage:extraArgs:downsampling.period:'{__name__=\"kube_persistentvolumeclaim_deletion_timestamp\"}:1d:10m,{__name__=\"kube_pod_init_container_status_last_terminated_reason\"}:1d:10m,7d:1m,30d:5m,180d:30m'# ... rest of your configuration ...
This configuration:
Applies 10-minute resolution downsampling for the rarely-queried metrics after just 1 day
Maintains your existing downsampling policy for all other metrics
The order of the downsampling rules is important - more specific rules should be listed first.
During this dialog, the assistant was using the following tools:
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
But you can use any other tools and combine them in your own way.
Why is the MCP server using more resources than I would expect from a simple API proxy?
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.
How to use one MCP server instance for several VictoriaMetrics instances?
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.
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.
Install
Configuration
Environment variables
VM_INSTANCE_ENTRYPOINTrequired
URL to VictoriaMetrics instance (it should be root URL of vmsingle or vmselect), for example http://localhost:8428 or https://play.victoriametrics.com
VM_INSTANCE_TYPErequired
Type of VictoriaMetrics instance (single / cluster)
VM_INSTANCE_BEARER_TOKENrequiredsecret
Authentication token for VictoriaMetrics API
VMC_API_KEYsecret
Optional: API key from VictoriaMetrics Cloud Console (if you have deployment in VictoriaMetrics Cloud)
MCP_DISABLED_TOOLS
Comma-separated list of tools to disable
MCP_DISABLE_RESOURCES
Disable all resources (documentation tool will continue to work)