mcp-victoriametrics

Сервер MCP VictoriaMetrics

Реализация сервера Model Context Protocol (MCP) для VictoriaMetrics .

Это обеспечивает доступ к вашему экземпляру VictoriaMetrics и бесшовную интеграцию с API и документацией VictoriaMetrics . Это может предоставить вам комплексный интерфейс для мониторинга, наблюдения и отладки задач, связанных с вашими экземплярами VictoriaMetrics, включить расширенные возможности автоматизации и взаимодействия для инженеров и инструментов.

Функции

Этот сервер MCP позволяет использовать почти все API VictoriaMetrics, доступные только для чтения, т. е. все функции, доступные в VMUI :

Запрос показателей и исследование данных (даже построение графиков, если ваш клиент это поддерживает)
Перечисление и экспорт доступных метрик, меток, значений меток и целых серий
Анализ правил оповещения и регистрации, а также оповещений
Отображение параметров вашего экземпляра VictoriaMetrics
Изучение мощности ваших данных и статистики использования метрик
Анализ ваших запросов
Отладка правил перемаркировки, понижения выборки и конфигураций политик хранения

Кроме того, сервер MCP содержит встроенную актуальную документацию и позволяет осуществлять поиск по ней без доступа в Интернет.

Более подробную информацию о доступных инструментах и подсказках можно найти в разделе «Использование» .

Вы можете объединить функциональность инструментов, поиска документов в ваших подсказках и придумать отличные сценарии использования для вашего экземпляра VictoriaMetrics. Просто проверьте раздел Пример диалога, чтобы увидеть, как это может работать. И, пожалуйста, обратите внимание на тот факт, что качество MCP Server и его ответов во многом зависит от возможностей вашего клиента и качества модели, которую вы используете.

Вы также можете объединить сервер MCP с другими серверами MCP, связанными с наблюдением или поиском документов, и получить еще более мощные результаты.

Требования

Экземпляр VictoriaMetrics ( одноузловой или кластерный )
Используйте версию 1.24 или выше (если вы хотите собрать из исходников)

Установка

Идти

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

Исходный код

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

Двоичные файлы

Просто загрузите последнюю версию со страницы «Релизы» и добавьте ее в PATH.

Докер

Вскоре...

Конфигурация

Сервер MCP для VictoriaMetrics настраивается с помощью переменных среды:

Переменная	Описание	Необходимый	По умолчанию	Допустимые значения
`VM_INSTANCE_ENTRYPOINT`	URL-адрес экземпляра VictoriaMetrics	Да	-	-
`VM_INSTANCE_TYPE`	Тип экземпляра VictoriaMetrics	Да	-	`single` , `cluster`
`VM_INSTANCE_BEARER_TOKEN`	Токен аутентификации для API VictoriaMetrics	Нет	-	-
`MCP_SERVER_MODE`	Режим работы сервера	Нет	`stdio`	`stdio` , `sse`
`MCP_SSE_ADDR`	Адрес для прослушивания сервером SSE	Нет	`localhost:8080`	-

Примеры конфигурации

# 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"

Настройка в клиентах

Курсор

Перейдите в: Settings -> Cursor Settings -> MCP -> Add new global MCP server и вставьте следующую конфигурацию в файл курсора ~/.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>"
      }
    }
  }
}

Более подробную информацию см. в документации Cursor MCP .

Клод Десктоп

Добавьте это в файл claude_desktop_config.json вашего рабочего стола Claude (его можно найти, открыв 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>"
      }
    }
  }
}

Более подробную информацию см. в документации Claude Desktop MCP .

Клод Код

Выполните команду:

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>

Более подробную информацию см. в документации Claude Code MCP .

Код Visual Studio

Добавьте это в файл конфигурации VS Code 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>"
      }
    }
  }
}

Более подробную информацию см. в документации VS Code MCP .

Зед

Добавьте следующее в файл конфигурации 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": {}
    }
  }

Более подробную информацию см. в документации Zed MCP .

JetBrains IDE

Откройте Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP) .
Нажмите Add (+)
Выбрать As 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>"
      }
    }
  }
}

Виндсерфинг

Добавьте следующее в файл конфигурации 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>"
      }
    }
  }
}

Более подробную информацию см. в документации Windsurf MCP .

Амазонка Бедрок

Вскоре....

Использование Docker вместо двоичного кода

Вскоре...

Использование

После установки и настройки сервера MCP вы можете начать использовать его с вашим любимым клиентом MCP.

Диалог с ИИ-помощником можно начать с фразы:

Use MCP VictoriaMetrics in the following answers

Но это не обязательно, вы можете просто начать задавать вопросы, и помощник автоматически будет использовать инструменты и документацию, чтобы предоставить вам лучшие ответы. Просто взгляните на раздел Пример диалога, чтобы лучше понять, что вы можете с ним сделать.

Набор инструментов

MCP VictoriaMetrics предоставляет многочисленные инструменты для взаимодействия с вашим экземпляром VictoriaMetrics.

Вот список доступных инструментов:

Инструмент	Описание
`query`	Выполнение мгновенных запросов PromQL/MetricsQL
`query_range`	Выполнение ряда запросов PromQL/MetricsQL за определенный период времени
`metrics`	Список доступных метрик
`labels`	Список доступных названий меток
`label_values`	Список значений для определенной метки
`series`	Список доступных временных рядов
`export`	Экспорт необработанных данных временного ряда в JSON или CSV
`rules`	Просмотр правил оповещения и записи
`alerts`	Просмотр текущих оповещений (активированных и ожидающих обработки)
`flags`	Просмотр нестандартных флагов экземпляра VictoriaMetrics
`metric_statistics`	Получить статистику использования метрик (в запросах)
`active_queries`	Просмотреть текущие выполняемые запросы
`top_queries`	Просмотреть наиболее частые или самые медленные запросы
`tsdb_status`	Просмотр статистики мощности TSDB
`tenants`	Список доступных арендаторов в многопользовательской кластерной настройке
`documentation`	Поиск во встроенной документации VictoriaMetrics
`metric_relabel_debug`	Отладка правил перемаркировки, совместимых с Prometheus
`downsampling_filters_debug`	Отладка конфигурации понижения частоты дискретизации
`retention_filters_debug`	Отладка конфигурации фильтров хранения

Подсказки

Сервер включает в себя предопределенные подсказки для выполнения распространенных задач.

На данный момент это всего лишь примеры, библиотека подсказок будет дополнена в будущем:

Быстрый	Описание
`unused_metrics`	Найдите метрики, которые никогда не запрашиваются, и создайте конфигурации перемаркировки, чтобы прекратить их прием
`documentation`	Поиск документации VictoriaMetrics по конкретным темам
`rarely_used_metrics_with_high_cardinality`	Определите метрики с высокой кардинальностью, которые редко запрашиваются

Обратите внимание, что даунсэмплинг — это функция Enterprise в VictoriaMetrics. Ваша текущая лицензия позволяет вам использовать ее, поскольку я вижу, что файл лицензии настроен.

Пример диалога

Это всего лишь пример диалога с Assistant, использующим MCP Server, который может помочь понять, как он работает (но это реальный диалог с использованием MCP-сервера Victoria Metrics с Claude Desktop и настроенным на общедоступный экземпляр игровой площадки ):

Вы : Какие арендаторы доступны в моей виртуальной машине?
Помощник В вашем экземпляре VictoriaMetrics доступны следующие арендаторы 0:0 (арендатор по умолчанию), 1:0 , 10:0 , 100:0
Вы : С этого момента, пожалуйста, используйте только арендатора по умолчанию.
Assistant : Я понимаю. С этого момента я буду использовать только арендатора по умолчанию (0:0) для всех операций с вашим экземпляром VictoriaMetrics.
Вы : Какие у нас есть показатели?
Assistant : В вашем экземпляре VictoriaMetrics доступно множество метрик. Список включает метрики из различных систем и компонентов, таких как:
- Системные метрики ( node_ , machine_ и т.д.),
- Метрики Kubernetes ( kube_ , container_ , apiserver_ и т. д.),
- Метрики, специфичные для VictoriaMetrics ( vm_ , vmagent_ , vmalert_ и т. д.),
- Метрики времени выполнения Go ( go_ ),
- Метрики, связанные с Prometheus ( scrape_ , promhttp_ ),
- Различные метрики приложения ( argocd_ , alertmanager_ ).
Это полный список из более чем 2000 метрик, доступных для запроса. Есть ли конкретный тип метрик, который вы хотели бы изучить подробнее?
Вы : Хорошо, давайте работать с метриками kubernetes с этого момента. Пожалуйста, покажите мне, какие из этих метрик никогда не запрашивались?
Помощник : Основываясь на результатах, я вижу, что есть две метрики Kubernetes, которые никогда не запрашивались (количество запросов равно 0):
- kube_persistentvolumeclaim_deletion_timestamp — эта метрика предоставляет информацию о том, когда PersistentVolumeClaims были помечены для удаления.
- kube_pod_init_container_status_last_terminated_reason — эта метрика показывает причину последнего завершения работы init-контейнеров в модулях.
Эти показатели могут быть полезны для мониторинга и устранения неполадок:
- Метрика временной метки удаления PVC может помочь отслеживать закономерности удаления или выявлять застрявшие PVC.
- Метрика причин завершения работы контейнера init может помочь выявить распространенные модели сбоев в контейнерах инициализации.
Хотите, чтобы я подробнее объяснил, что отслеживают эти показатели, или предложил несколько полезных запросов, чтобы начать их мониторинг?
Вы : Да, пожалуйста. А также, можете ли вы создать правила перемаркировки, чтобы прекратить прием этих метрик?
Assistant : Я создам конфигурацию перемаркировки, чтобы исключить эти никогда не запрашиваемые метрики из сбора. Это поможет сократить накладные расходы на хранение и обработку. Вот конфигурация перемаркировки, которую вы можете добавить в конфигурацию скрапа VictoriaMetrics:
relabel_configs: - action: drop source_labels: [__name__] regex: kube_persistentvolumeclaim_deletion_timestamp|kube_pod_init_container_status_last_terminated_reason
Эта конфигурация будет:
1. Посмотрите на название каждой метрики (метка __name__ )
2. Проверьте, соответствует ли он хотя бы одной из указанных метрик.
3. Удалить соответствующие показатели, не дав им собраться и сохраниться.
Вы можете добавить это в файл конфигурации VictoriaMetrics или в соответствующие конфигурации заданий по очистке в конфигурации Prometheus, если вы используете Prometheus в качестве очистителя для VictoriaMetrics. Если вы хотите протестировать эту конфигурацию перемаркировки перед ее реализацией, вы можете использовать инструмент отладки перемаркировки метрики, чтобы увидеть, как она повлияет на ваши метрики.
Вы : Да, пожалуйста, отладьте эту конфигурацию перемаркировки в реальном времени, чтобы увидеть, как это повлияет на мои метрики.
Assistant : Отлично! Конфигурация перемаркировки работает так, как и ожидалось:
- Первые два тестовых случая показывают, что метрики kube_persistentvolumeclaim_deletion_timestamp и kube_pod_init_container_status_last_terminated_reason корректно удаляются (результирующие метки пустые {} ).
- Третий тестовый случай подтверждает, что другие метрики, такие как kube_pod_status_phase , сохраняются и не затрагиваются нашим правилом удаления.
Вы можете уверенно добавить эту конфигурацию перемаркировки в конфигурацию VictoriaMetrics или Prometheus, чтобы прекратить сбор этих неиспользуемых метрик. Это сэкономит место на диске и сократит накладные расходы на обработку, не влияя на ваши текущие возможности мониторинга.
Вы : Но я использую ресурс vmagent оператора VictoriaMetrics. Не могли бы вы предоставить мне часть спецификации для моего агента с этой конфигурацией переименования?
Assistant : Вы правы, поскольку вы используете оператор VictoriaMetrics и пользовательский ресурс VMAgent, конфигурация должна быть в соответствующем формате для этого CR. Вот как вы можете добавить конфигурацию relabel в свою спецификацию 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 ...
Ключевые моменты:
- В спецификации VMAgent вы используете inlineRelabelConfig для правил встроенной перемаркировки.
- Поле называется sourceLabels (а не source_labels как в конфигурации Prometheus)
- Это глобальная перемаркировка, которая будет применена ко всем метрикам перед их сохранением.
Вы : Я решил не удалять эти метрики, а просто понизить частоту выборки для них с помощью Downsampling. Какие параметры downsampling у меня сейчас?
Помощник : Я вижу, что в настоящее время у вас следующая конфигурация понижения частоты дискретизации:
-downsampling.period="7d:1m,30d:5m,180d:30m"
Это означает:
- Данные старше 7 дней сохраняются в исходном разрешении.
- Данные возрастом от 7 до 30 дней сжимаются до разрешения в 1 минуту.
- Данные возрастом от 30 до 180 дней сжимаются до разрешения в 5 минут.
- Данные старше 180 дней сжимаются до 30-минутного разрешения.
Теперь, если вы хотите добавить определенные правила понижения выборки для этих редко запрашиваемых метрик, вы можете использовать отладочный инструмент фильтров понижения выборки, чтобы проверить, как будут работать новые правила. Давайте протестируем конфигурацию, в которой мы применяем более агрессивную понижение выборки к этим конкретным метрикам:
...получение серий и использование отладчика фильтра понижения частоты дискретизации...
Отлично! Теперь наш тест работает правильно. На основе текущей конфигурации и нашего тестирования предлагаем следующую конфигурацию понижения частоты дискретизации для вашего VMAgent CR, которая применит более агрессивную понижение частоты дискретизации к редко запрашиваемым метрикам:
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 ...
Эта конфигурация:
- Применяет понижение разрешения на 10 минут для редко запрашиваемых метрик всего через 1 день. - Сохраняет существующую политику понижения разрешения для всех остальных метрик.
Порядок правил понижения разрешения важен — более конкретные правила следует перечислить первыми.

Во время этого диалога помощник использовал следующие инструменты:

tenants , чтобы получить список доступных арендаторов
documentation для получения информации о функциональности и форматах данных
metrics для получения списка доступных метрик
metrics_staistics для получения информации об использовании метрик
series для получения временных рядов для отладки
metric_relabel_debug для отладки правил перемаркировки
flags для получения информации о параметрах экземпляра
downsampling_filters_debug для отладки конфигурации понижения частоты дискретизации

Но вы можете использовать любые другие инструменты и комбинировать их по-своему.

Отказ от ответственности

Службы и агенты ИИ вместе с серверами MCP, как этот, не могут гарантировать точность, полноту и надежность результатов. Вам следует дважды проверить результаты, полученные с помощью ИИ. Качество сервера MCP и его ответов во многом зависит от возможностей вашего клиента и качества модели, которую вы используете.

Внося вклад

Приветствуются вклады в проект MCP VictoriaMetrics! Не стесняйтесь отправлять вопросы, запросы на функции или запросы на извлечение.