Best for
- Developers and SREs using VictoriaMetrics for monitoring and observability.
- Engineers who want to leverage AI assistants to simplify metric queries and operations.
- Teams needing quick access to documentation and troubleshooting guides.
V
VictoriaMetrics MCP Server
Official
Official VictoriaMetrics MCP server for seamless integration with VictoriaMetrics API and documentation.
GitHub source repository ↗
69FMRS · C
VictoriaMetrics MCP Server is an official, high-quality server with a rich toolset and documentation search, well-suited for monitoring scenarios. Setup is straightforward, but attention should be paid to resource consumption and API permission management.
VictoriaMetrics MCP Server is the official implementation of the Model Context Protocol (MCP) server for VictoriaMetrics. It provides AI assistants with the ability to interact with VictoriaMetrics instances, enabling natural language querying of metrics, data exploration, alert rule analysis, relabel configuration debugging, and more. It includes an embedded vector database of VictoriaMetrics documentation for offline search. The server supports multiple transport modes (stdio, SSE, Streamable HTTP) and is configurable via environment variables.
Tools
query
Execute instant PromQL/MetricsQL queries
query_range
Execute range PromQL/MetricsQL queries over a time period
metrics
List available metrics
metrics_metadata
Get stored metrics metadata (type, help, unit)
labels
List available label names
label_values
List values for a specific label
series
List available time series
export
Export raw time series data to JSON or CSV (disabled by default)
rules
View alerting and recording rules
alerts
View current alerts (firing and pending)
flags
View non-default flags of the VictoriaMetrics instance (disabled by default)
metric_statistics
Get metrics usage (in queries) statistics
active_queries
View currently executing queries
top_queries
View most frequent or slowest queries
tsdb_status
View TSDB cardinality statistics
tenants
List available tenants in multi-tenant cluster setup
documentation
Search in embedded VictoriaMetrics documentation
metric_relabel_debug
Debug Prometheus-compatible relabeling rules (disabled by default)
downsampling_filters_debug
Debug downsampling configuration (disabled by default)
retention_filters_debug
Debug retention filters configuration (disabled by default)
prettify_query
Prettify and format PromQL/MetricsQL queries
explain_query
Parse PromQL/MetricsQL queries and explain how it works
test_rules
Unit-test alerting and recording rules using vmalert tool (disabled by default)
deployments
List available deployments in VictoriaMetrics Cloud
cloud_providers
List available cloud providers in VictoriaMetrics Cloud
regions
List available cloud providers regions in VictoriaMetrics Cloud
tiers
List available deployment tiers in VictoriaMetrics Cloud
access_tokens
List available deployment access tokens in VictoriaMetrics Cloud
rule_filenames
List available alerting and recording rule filenames in VictoriaMetrics Cloud
rule_file
Content of a specific alerting or recording rule file in VictoriaMetrics Cloud
Setup
- Download the binary from GitHub Releases, or use Docker:
docker run -d --name mcp-victoriametrics -e VM_INSTANCE_ENTRYPOINT=... -e VM_INSTANCE_TYPE=... -p 8080:8080 ghcr.io/victoriametrics/mcp-victoriametrics. - Set environment variables:
VM_INSTANCE_ENTRYPOINT(required, root URL of VictoriaMetrics instance) andVM_INSTANCE_TYPE(required, single or cluster). Optional:VM_INSTANCE_BEARER_TOKEN,VM_INSTANCE_HEADERS,VMC_API_KEYfor Cloud. - Configure the server in your MCP client, specifying the command path and environment variables. For example, for Claude Desktop, edit
claude_desktop_config.json.
Fit and risk
Not for
- Users who do not use VictoriaMetrics; this server is not suitable for other monitoring systems.
- Scenarios requiring write or modify operations, as the server only supports read-only APIs.
- Environments sensitive to resource consumption, as the embedded documentation vector database may increase memory and CPU usage.
Required permissions
- Read access to VictoriaMetrics instance APIs (query, list metrics, export data, etc.).
- If using Cloud mode, access to VictoriaMetrics Cloud API key.
- Network access to connect to the VictoriaMetrics instance or Cloud service may be required.
Risks and side effects
- Need to carefully manage API tokens to avoid leaking sensitive data.
- AI-generated queries and configurations may contain errors; should be verified before use in production.
- The server may consume significant resources, especially when loading the documentation vector database; can save resources by disabling the documentation tool.
Troubleshooting
- Ensure `VM_INSTANCE_ENTRYPOINT` is a reachable root URL (e.g., http://localhost:8428) and the instance type is correct (single or cluster).
- Check that environment variables are set correctly, especially authentication tokens.
- If using Cloud mode, ensure `VMC_API_KEY` is valid and has required permissions.
- Check server logs (set `MCP_LOG_LEVEL` to debug) for error details.
- In SSE/HTTP modes, use `/health/liveness` and `/health/readiness` endpoints to check server status.
Use cases
Query metrics and explore data via natural language, without writing PromQL manually.
Analyze alerting and recording rules, debug relabel configurations.
Monitor VictoriaMetrics instance health, including cardinality, query statistics, and active queries.
Search official documentation and blogs for quick troubleshooting information.
Integrate with VictoriaMetrics Cloud to manage deployments and access tokens.
Supported clients
Claude DesktopFull support
CursorFull support
Claude CodePartial support
CodexPartial support
Visual Studio CodeFull support
ZedFull support
JetBrains IDEsPartial support
WindsurfFull support