mcp-victoriametrics

Servidor MCP de VictoriaMetrics

La implementación del servidor de Protocolo de Contexto de Modelo (MCP) para VictoriaMetrics .

Esto proporciona acceso a su instancia de VictoriaMetrics y una integración fluida con las API y la documentación de VictoriaMetrics . Le ofrece una interfaz completa para las tareas de monitoreo, observabilidad y depuración relacionadas con sus instancias de VictoriaMetrics, además de habilitar capacidades avanzadas de automatización e interacción para ingenieros y herramientas.

Características

Este servidor MCP le permite utilizar casi todas las API de solo lectura de VictoriaMetrics, es decir, todas las funciones disponibles en VMUI :

Consultar métricas y explorar datos (incluso dibujar gráficos si su cliente lo admite)
Listado y exportación de métricas, etiquetas, valores de etiquetas y series completas disponibles
Análisis de sus reglas y alertas de grabación y alertas
Mostrar parámetros de su instancia de VictoriaMetrics
Explorando la cardinalidad de sus datos y estadísticas de uso de métricas
Analizando sus consultas
Depuración de sus reglas de reetiquetado, reducción de muestreo y configuraciones de políticas de retención

Además, el servidor MCP contiene documentación actualizada incorporada y puede buscarla sin acceso en línea.

Puede encontrar más detalles sobre las herramientas y indicaciones exactas disponibles en la sección Uso .

Puede combinar la funcionalidad de herramientas y la búsqueda de documentos en sus indicaciones e idear escenarios de uso excelentes para su instancia de VictoriaMetrics. Simplemente consulte la sección de ejemplo de diálogo para ver cómo funciona. Tenga en cuenta que la calidad del servidor MCP y sus respuestas dependen en gran medida de las capacidades de su cliente y de la calidad del modelo que utilice.

También puede combinar el servidor MCP con otros servidores MCP relacionados con la observación o la búsqueda de documentos y obtener resultados aún más potentes.

Requisitos

Instancia de VictoriaMetrics ( nodo único o clúster )
Vaya a 1.24 o superior (si desea compilar desde la fuente)

Instalación

Ir

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

Código fuente

git clone https://github.com/VictoriaMetrics-Community/mcp-victoriametrics.git
cd mcp-victoriametrics
go build -o bin/mcp-victoriametrics ./cmd/mcp-victoriametrics/main.go

# after that add bin/mcp-victoriametrics file to your PATH

Binarios

Simplemente descargue la última versión desde la página de versiones y colóquela en su RUTA.

Estibador

Muy pronto...

Configuración

El servidor MCP para VictoriaMetrics se configura a través de variables de entorno:

Variable	Descripción	Requerido	Por defecto	Valores permitidos
`VM_INSTANCE_ENTRYPOINT`	URL a la instancia de VictoriaMetrics	Sí	-	-
`VM_INSTANCE_TYPE`	Tipo de instancia de VictoriaMetrics	Sí	-	`single` , `cluster`
`VM_INSTANCE_BEARER_TOKEN`	Token de autenticación para la API de VictoriaMetrics	No	-	-
`MCP_SERVER_MODE`	Modo de funcionamiento del servidor	No	`stdio`	`stdio` , `sse`
`MCP_SSE_ADDR`	Dirección para que el servidor SSE escuche	No	`localhost:8080`	-

Ejemplos de configuración

# For a single-node instance
export VM_INSTANCE_ENTRYPOINT="http://localhost:8428"
export VM_INSTANCE_TYPE="single"
export VM_INSTANCE_BEARER_TOKEN="your-token"

# For a cluster
export VM_INSTANCE_ENTRYPOINT="https://play.victoriametrics.com"
export VM_INSTANCE_TYPE="cluster"

# Server mode
export MCP_SERVER_MODE="sse"
export MCP_SSE_ADDR="0.0.0.0:8080"

Configuración en clientes

Cursor

Vaya a: Settings -> Cursor Settings -> MCP -> Add new global MCP server y pegue la siguiente configuración en su archivo Cursor ~/.cursor/mcp.json :

{
  "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>"
      }
    }
  }
}

Consulte la documentación de Cursor MCP para obtener más información.

Escritorio de Claude

Agregue esto a su archivo claude_desktop_config.json de Claude Desktop (puede encontrarlo si abre 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>"
      }
    }
  }
}

Consulte la documentación de Claude Desktop MCP para obtener más información.

Claude Code

Ejecute el comando:

claude mcp add victoriametrics -- /path/to/mcp-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>

Consulte la documentación de Claude Code MCP para obtener más información.

Código de Visual Studio

Agregue esto a su archivo de configuración MCP de VS Code:

{
  "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>"
      }
    }
  }
}

Consulte la documentación de VS Code MCP para obtener más información.

Zed

Agregue lo siguiente a su archivo de configuración de Zed:

  "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>"
        }
      },
      "settings": {}
    }
  }

Consulte la documentación de Zed MCP para obtener más información.

IDE de JetBrains

Abra Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP) .
Haga clic Add (+)
Seleccionar As JSON
Coloque lo siguiente en el campo de entrada:

{
  "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>"
      }
    }
  }
}

Windsurf

Agregue lo siguiente a su archivo de configuración Windsurf 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>"
      }
    }
  }
}

Consulte la documentación de Windsurf MCP para obtener más información.

Amazon Bedrock

Muy pronto....

Usando Docker en lugar de binario

Muy pronto...

Uso

Después de instalar y configurar el servidor MCP, puede comenzar a usarlo con su cliente MCP favorito.

Puedes iniciar un diálogo con el asistente de IA desde la frase:

Use MCP VictoriaMetrics in the following answers

Pero no es obligatorio; puedes empezar a hacer preguntas y el asistente usará automáticamente las herramientas y la documentación para ofrecerte las mejores respuestas. Consulta la sección de ejemplos de Dialog para comprender mejor sus funciones.

Conjunto de herramientas

MCP VictoriaMetrics proporciona numerosas herramientas para interactuar con su instancia de VictoriaMetrics.

Aquí hay una lista de herramientas disponibles:

Herramienta	Descripción
`query`	Ejecutar consultas instantáneas de PromQL/MetricsQL
`query_range`	Ejecutar consultas PromQL/MetricsQL de rango durante un período de tiempo
`metrics`	Lista de métricas disponibles
`labels`	Lista de nombres de etiquetas disponibles
`label_values`	Lista de valores para una etiqueta específica
`series`	Lista de series temporales disponibles
`export`	Exportar datos de series de tiempo sin procesar a JSON o CSV
`rules`	Ver reglas de alerta y grabación
`alerts`	Ver alertas actuales (activadas y pendientes)
`flags`	Ver indicadores no predeterminados de la instancia VictoriaMetrics
`metric_statistics`	Obtener estadísticas de uso de métricas (en consultas)
`active_queries`	Ver las consultas que se están ejecutando actualmente
`top_queries`	Ver las consultas más frecuentes o más lentas
`tsdb_status`	Ver las estadísticas de cardinalidad de TSDB
`tenants`	Enumerar los inquilinos disponibles en la configuración de un clúster multiinquilino
`documentation`	Buscar en la documentación integrada de VictoriaMetrics
`metric_relabel_debug`	Depurar reglas de reetiquetado compatibles con Prometheus
`downsampling_filters_debug`	Configuración de depuración de disminución de muestreo
`retention_filters_debug`	Configuración de filtros de retención de depuración

Indicaciones

El servidor incluye indicaciones predefinidas para tareas comunes.

Estos son solo ejemplos por el momento, la biblioteca de indicaciones se agregará en el futuro:

Inmediato	Descripción
`unused_metrics`	Encuentre métricas que nunca se consultan y cree configuraciones de reetiquetado para dejar de ingerirlas
`documentation`	Busque documentación de VictoriaMetrics para temas específicos
`rarely_used_metrics_with_high_cardinality`	Identificar métricas de alta cardinalidad que rara vez se consultan

Tenga en cuenta que la reducción de resolución es una función empresarial de VictoriaMetrics. Su licencia actual le permite usarla, ya que el archivo de licencia está configurado.

Ejemplo de diálogo

Este es solo un ejemplo de diálogo con el Asistente que usa el servidor MCP que puede ayudar a comprender cómo puede funcionar (pero es un diálogo real con el uso del servidor MCP de Victoria Metrics con Claude Desktop y configurado para una instancia de juegos pública ):

Tú : ¿Qué inquilinos están disponibles en mi máquina virtual?
Asistente En su instancia de VictoriaMetrics, los siguientes inquilinos están disponibles 0:0 (inquilino predeterminado), 1:0 , 10:0 , 100:0
Tú : De ahora en adelante, utiliza únicamente el inquilino predeterminado
Asistente : Entiendo. De ahora en adelante, usaré solo el inquilino predeterminado (0:0) para todas las operaciones con su instancia de VictoriaMetrics.
Tú : ¿Qué métricas tenemos?
Asistente : Hay muchas métricas disponibles en su instancia de VictoriaMetrics. La lista incluye métricas de varios sistemas y componentes, como:
- Métricas del sistema ( node_ , machine_ , etc.),
- Métricas de Kubernetes ( kube_ , container_ , apiserver_ , etc.)
- Métricas específicas de VictoriaMetrics ( vm_ , vmagent_ , vmalert_ , etc.)
- Métricas de tiempo de ejecución de Go ( go_ ),
- Métricas relacionadas con Prometheus ( scrape_ , promhttp_ ),
- Varias métricas de aplicación ( argocd_ , alertmanager_ ).
Esta es una lista completa de más de 2000 métricas disponibles para consulta. ¿Hay alguna métrica específica que le interese explorar más a fondo?
Tú : Bien, a partir de ahora trabajaremos con las métricas de Kubernetes. ¿Podrías decirme cuáles de estas métricas nunca se consultaron?
Asistente : Según los resultados, puedo ver que hay dos métricas de Kubernetes que nunca se han consultado (el recuento de consultas es 0):
- kube_persistentvolumeclaim_deletion_timestamp : esta métrica proporciona información sobre cuándo se marcaron los PersistentVolumeClaims para su eliminación.
- kube_pod_init_container_status_last_terminated_reason : esta métrica muestra el motivo por el cual los contenedores de inicio en los pods se finalizaron por última vez.
Estas métricas pueden ser valiosas para fines de monitoreo y resolución de problemas:
- La métrica de marca de tiempo de eliminación de PVC podría ayudar a rastrear patrones de eliminación o identificar PVC atascados.
- La métrica del motivo de finalización del contenedor de inicialización podría ayudar a identificar patrones de falla comunes en sus contenedores de inicialización.
¿Quieres que te explique más sobre qué rastrean estas métricas o te sugiera algunas consultas útiles para comenzar a monitorearlas?
Tú : Sí, por favor. Y, además, ¿podrías crear reglas de reetiquetado para dejar de ingerir estas métricas?
Asistente : Crearé una configuración de reetiquetado para excluir de la recopilación estas métricas que nunca se consultan. Esto ayudará a reducir la sobrecarga de almacenamiento y procesamiento. Aquí está la configuración de reetiquetado que puede agregar a su configuración de scraping de VictoriaMetrics:
relabel_configs: - action: drop source_labels: [__name__] regex: kube_persistentvolumeclaim_deletion_timestamp|kube_pod_init_container_status_last_terminated_reason
Esta configuración hará lo siguiente:
1. Mira el nombre de cada métrica (la etiqueta __name__ )
2. Comprueba si coincide con alguna de las métricas especificadas
3. Eliminar las métricas que coinciden, evitando que se recopilen y almacenen
Puede agregar esto a su archivo de configuración de VictoriaMetrics o a las configuraciones de trabajo de scraping relevantes en su configuración de Prometheus si usa Prometheus como scraper para VictoriaMetrics. Si desea probar esta configuración de reetiquetado antes de implementarla, puede usar la herramienta de depuración de reetiquetado de métricas para ver cómo afectaría a sus métricas.
Tú : Sí, depura esta configuración de reetiquetado en series de tiempo real para ver cómo afectaría mis métricas.
Asistente : ¡Perfecto! La configuración de reetiquetado funciona correctamente.
- Los primeros dos casos de prueba muestran que las métricas kube_persistentvolumeclaim_deletion_timestamp y kube_pod_init_container_status_last_terminated_reason se eliminan correctamente (las etiquetas resultantes están vacías {} ).
- El tercer caso de prueba confirma que otras métricas como kube_pod_status_phase se conservan y no se ven afectadas por nuestra regla de eliminación.
Puede agregar con confianza esta configuración de reetiquetado a su configuración de VictoriaMetrics o Prometheus para dejar de recopilar estas métricas no utilizadas. Esto ahorrará espacio de almacenamiento y reducirá la sobrecarga de procesamiento sin afectar sus capacidades de monitorización actuales.
Tú : Pero estoy usando el recurso vmagent del operador VictoriaMetrics, ¿podrías darme parte de las especificaciones para mi agente con esta configuración de reetiquetado?
Asistente : Tienes razón. Dado que estás usando el operador VictoriaMetrics y el recurso personalizado VMAgent, la configuración debe tener el formato adecuado para esa CR. Así es como puedes agregar la configuración de reetiquetado a tu especificación de VMAgent:
apiVersion: operator.victoriametrics.com/v1beta1 kind: VMAgent metadata: name: your-vmagent-name spec: # ... your existing configuration ... # Add this section to configure global metric relabeling inlineRelabelConfig: - action: drop sourceLabels: ["__name__"] regex: kube_persistentvolumeclaim_deletion_timestamp|kube_pod_init_container_status_last_terminated_reason # ... rest of your configuration ...
Puntos clave:
- En la especificación de VMAgent, utilice inlineRelabelConfig para las reglas de reetiquetado en línea
- El campo se llama sourceLabels (no source_labels como en la configuración de Prometheus)
- Este es un reetiquetado global que se aplicará a todas las métricas antes de que se almacenen.
Tú : Decidí no eliminar esas métricas, sino simplemente reducir su frecuencia de muestreo mediante la función de submuestreo. ¿Qué parámetros de submuestreo tengo ahora?
Asistente : Puedo ver que actualmente tienes la siguiente configuración de reducción de muestreo:
-downsampling.period="7d:1m,30d:5m,180d:30m"
Esto significa:
- Los datos más recientes de 7 días se mantienen en su resolución original.
- Los datos de entre 7 y 30 días de antigüedad se reducen a una resolución de 1 minuto.
- Los datos de entre 30 y 180 días de antigüedad se reducen a una resolución de 5 minutos.
- Los datos con más de 180 días de antigüedad se reducen a una resolución de 30 minutos.
Ahora, si desea agregar reglas de submuestreo específicas para las métricas que rara vez se consultan, puede usar la herramienta de depuración de filtros de submuestreo para probar el funcionamiento de las nuevas reglas. Probemos una configuración donde aplicamos un submuestreo más agresivo a esas métricas específicas:
...obteniendo series y usando el depurador de filtro de reducción de muestreo...
¡Genial! Nuestra prueba ahora funciona correctamente. Basándonos en la configuración actual y en nuestras pruebas, sugerimos una configuración de submuestreo para su CR de VMAgent que aplicaría un submuestreo más agresivo a las métricas que rara vez se consultan:
apiVersion: operator.victoriametrics.com/v1beta1 kind: VMCluster metadata: name: monitoring-vm-cluster spec: # ... your existing configuration ... # Update the vmstorage section with the new downsampling parameters vmstorage: 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 ...
Esta configuración:
- Aplica un muestreo descendente con una resolución de 10 minutos para las métricas que rara vez se consultan después de solo 1 día. - Mantiene su política de muestreo descendente existente para todas las demás métricas.
El orden de las reglas de reducción de muestreo es importante: las reglas más específicas deben enumerarse primero.

Durante este diálogo, el asistente estaba utilizando las siguientes herramientas:

tenants para obtener la lista de inquilinos disponibles
documentation para obtener información sobre la funcionalidad y los formatos de datos
metrics para obtener la lista de métricas disponibles
metrics_staistics para obtener información sobre el uso de métricas
series para obtener la serie temporal para depuración.
metric_relabel_debug para depurar reglas de reetiquetado
flags para obtener la información sobre los parámetros de instancia
downsampling_filters_debug para depurar la configuración de reducción de muestreo

Pero puedes utilizar cualquier otra herramienta y combinarlas a tu manera.

Descargo de responsabilidad

Los servicios y agentes de IA, junto con los servidores MCP como este, no pueden garantizar la precisión, integridad ni fiabilidad de los resultados. Debe verificar los resultados obtenidos con IA. La calidad del servidor MCP y sus respuestas dependen en gran medida de las capacidades de su cliente y de la calidad del modelo que utilice.

Contribuyendo

¡Agradecemos sus contribuciones al proyecto MCP VictoriaMetrics! No dude en enviar problemas, solicitudes de funcionalidad o solicitudes de incorporación de cambios.