Elasticsearch 7.x MCP Server

MCP Server для подключения к вашему кластеру Elasticsearch напрямую из любого MCP-клиента (например, Claude Desktop, Cursor).

[!IMPORTANT] Этот форк ориентирован только на Elasticsearch 7.x. Он использует клиент @elastic/elasticsearch версии 7.17, чья проверка продукта принимает серверы старше 7.14. Для кластера Elasticsearch 8.x используйте вышестоящий проект @awesome-ai/elasticsearch-mcp, от которого этот форк произведён: клиент 8.x не может работать с сервером 7.x, и наоборот.

Этот сервер подключает агентов к вашим данным в Elasticsearch через Model Context Protocol. Он позволяет взаимодействовать с вашими индексами Elasticsearch через естественно-языковые диалоги.

Обзор возможностей

Инструменты разделены на три набора. Только первый доступен всегда; остальные подключаются явно через переменную окружения, поэтому боевое развёртывание может предоставить диагностику, не открывая удаление. Проверка доступа происходит при регистрации: отключённый инструмент никогда не появляется в tools/list, поэтому модель не может его вызвать, и он ни разу не занимает контекст агента.

Всегда доступны — чтение и запись данных

Кластер

• elasticsearch_health: здоровье кластера, опционально до уровня индекса

• cluster_info: имя кластера, версия Elasticsearch и тип сборки

Операции с индексами

• list_indices: список индексов, фильтрация по wildcard Elasticsearch (log-*)

• create_index: создать индекс с опциональными настройками и маппингами

• reindex: скопировать индекс, опционально с фильтром по запросу или с преобразованием через скрипт

• get_aliases: какие алиасы ссылаются на какие индексы

Маппинги

• get_mappings: поля индекса в виде точечных путей с типами, затем исходный маппинг

• create_mapping: создать или обновить маппинг индекса

Поиск и данные

• search: выполнить поиск по query DSL, с добавлением подсветки по всем текстовым полям — включая вложенные — если только в самом запросе не указан highlight

• count: сколько документов соответствует запросу, без выгрузки самих документов

• get_document: получить один документ по id

• bulk: массово проиндексировать много документов

Шаблоны

• create_index_template: создать или обновить компонуемый шаблон индекса

• get_index_template: прочитать шаблоны индексов

Задачи

• get_task: прогресс длительной операции, например той, что возвращает reindex

ES_ADMIN_TOOLS=true — диагностика (только чтение)

Эти инструменты только читают данные, поэтому их безопасно включать в проде — и в этом их суть: агент может объяснить, почему индекс нездоров, без того, чтобы кто-то заходил в кластер.

• explainallocation: почему шард не назначен, с решением каждого аллокатора

• list_shards: состояние на уровне шардов; первыми перечислены копии, которые не в статусе STARTED

• list_nodes: heap, CPU, load и давление на диск по каждому узлу

• get_index_stats: счётчики по индекс — размер, сегменты, индексация, поиск, слияния

• get_index_settings: настройки индекса (refresh_interval, реплики, блокировки на только чтение)

• get_cluster_settings: параметры кластера, переопределённые во время выполнения

• list_tasks: что кластер сейчас выполняет

ES_ALLOW_DESTRUCTIVE=true — необратимые операции

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

• delete_index: удалить индекс и его данные

• delete_document: удалить один документ по id

• delete_by_query: удалить все документы по запросу — асинхронная операция, возвращает id задачи, удаление продолжается в фоне

• delete_index_template: удалить шаблон индекса

Даже при включённом флаге эти инструменты отказываются работать с wildcard, списком через запятую, * и _all: они действуют только на один индексированный индекс. Модель, которая ошибочно примет logs-* за один индекс, получит отказ вместо опустошённого кластера.

Как это работает

1. MCP-клиент анализирует ваш запрос и определяет, какие операции Elasticsearch необходимы.

2. MCP-сервер выполняет эти операции (перечисляет индексы, получает маппинги, выполняет поиск).

3. MCP-клиент обрабатывает результаты и представляет их в пользудля пользователя виде.

Related MCP server: Elasticsearch 7.x MCP Server

Начало работы

Предварительные требования

• Экземпляр Elasticsearch 7.x (проверено на 7.8; клиент 7.17 поддерживает 6.8 и 7.x)

• Учётные данные Elasticsearch — API-ключ или имя пользователя с паролем

• MCP-клиент: Claude Code, Claude Desktop, Codex, Cursor или любой другой, умеющий MCP через stdio

Аутентификация в GitHub Packages, один раз

[!IMPORTANT] Этот пакет публикуется в GitHub Packages, а не npmjs.com, и GitHub Packages требует токен даже для публичных пакетов. Пока вы его не добавите, каждая установка ниже будет завершаться с ошибкой 401. Поместите его в пользовательский ~/.npmrc:

@agrica:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

YOUR_GITHUB_TOKEN — это personal access token с правом read:packages.

Храните его в своём ~/.npmrc, а не в файле проекта — токен, записанный в репозиторий, это утёкший токен, а некоторые менеджеры пакетов отказываются читать его оттуда.

Подключение к вашему клиенту

Каждый пример ниже заполняет ES_HOST и ES_API_KEY. Замените их на ES_USERNAME/ES_PASSWORD для базовой аутентификации, добавьте ES_ADMIN_TOOLS=true, чтобы получить диагностические инструменты, и укажите ES_INSTANCE_LABEL, когда объявлено несколько экземпляров — см. Параметры конфигурации.

claude mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  --env ES_ADMIN_TOOLS=true \
  -- npx -y @agrica/elasticsearch7-mcp

Затем команда /mcp в сессии покажет сервер и его инструменты.

Две детали, в которых легко ошибиться:

• Всё после -- — это команда, которая запускает сервер; без -- Claude Code попытается интерпретировать -y как свой собственный флаг.

• Не ставьте имя сервера сразу после --env — CLI прочитает его как ещё одну пару KEY=value и вернёт ошибку. В примере выше имя идёт первым, поэтому всё работает.

Сервер добавляется в локальной области видимости, поэтому он загружается только в текущем проекте. Добавьте --scope user, чтобы он был доступен везде, или --scope project, чтобы записать его в .mcp.json и поделиться с командой — но имейте в виду: закоммиченный .mcp.json будет содержать ваш API-ключ, поэтому для учётных данных лучше использовать user scope.

Отредактируйте claude_desktop_config.json — Settings > Developer > Edit Config открывает его, или найдите его по пути %APPDATA%\Claude\ на Windows и ~/Library/Application Support/Claude/ на macOS:

{
  "mcpServers": {
    "elasticsearch7": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://your-cluster:9200",
        "ES_API_KEY": "your-api-key",
        "ES_ADMIN_TOOLS": "true"
      }
    }
  }
}

После этого перезапустите Claude Desktop; он читает этот файл только при запуске.

codex mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  -- npx -y @agrica/elasticsearch7-mcp

Или впишите его вручную в ~/.codex/config.toml. Обратите внимание, что Codex записывает таблицу mcp_servers с подчёркиванием, а переменные окружения указываются в отдельной подтаблице, а не инлайн:

[mcp_servers.elasticsearch7]
command = "npx"
args = ["-y", "@agrica/elasticsearch7-mcp"]

[mcp_servers.elasticsearch7.env]
ES_HOST = "https://your-cluster:9200"
ES_API_KEY = "your-api-key"
ES_ADMIN_TOOLS = "true"

/mcp внутри Codex подтвердит, что сервер загружен.

The сервер — это обычный stdio MCP-сервер, поэтому с ним будет работать всё, что есть в списке MCP-клиентов. Ему нужны три вещи: команда npx, аргументы -y @agrica/elasticsearch7-mcp и переменные ES_* в его окружении. Он никогда не показывает порт и пишет в stdout только данные протокола MCP, а все диагностические сообщения отправляет в stderr.

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

Elasticsearch MCP Server поддерживает параметры конфигурации для подключения к вашему Elasticsearch:

[!NOTE] Вы должны указать либо API-ключ, либо имя пользователя и пароль для аутентификации.

[!WARNING] ES_ADMIN_TOOLS и ES_ALLOW_DESTRUCTIVE не имеют устаревшего псевдонима без префикса, в отличие от переменных подключения выше. Это намеренно: одно голое ADMIN_TOOLS или ALLOW_DESTRUCTIVE в окружении слишком легко оставить случайно — а ведь оно управляет достпуности удаления.

Обе переменные принимают true или 1; всё остальное, включая неопределённое значение, означает выключено.

Размер результата

Результат инструмента ограничен объёмом 32 KB (ES_MAX_RESULT_BYTES). Это важно для кластеров с логами: до введения ограничения один вызов list_shards по году ежедневных индексов возвращал 385 KB — примерно 96 000 токенов — в одном ответе, что больше, чем может удерживать большинство сессий.

Когда результат урезан, он это сообщает — и сколько было урезано, и как задать вопрос меньшим масштабом. Три инструмента строят свой результат с учётом этого ограничения:

• list_indices и list_shards возвращают читаемое резюме; те же строки как текст доступны через verbose.

• search ограничивает size до 100 за вызов и сообщает from, чтобы листать.

• get_mappings сначала перечисляет поля, а потом сырой маппинг — поэтому даже индекс с тысячью полей всё ещё отвечает на заданный вопрос.

Четыре инструмента — list_indices, list_shards, get_index_settings и get_mappings — также возвращают ответ в виде типизированной структурированной выдачи, чтобы клиент мог читать строки, а не только разбирать текст. Эта выдача собрана из того объёма, который остаётся после читаемого ответа, и показывает returned против total, чтобы частичная выборка была видна как число.

Изначать pnpm run measure на собранном выходе, чтобы посмотреть актуальные цифры для вашей конфигурации.

Именование нескольких экземпляров

Во многих установках этот сервер объявляется несколько раз — по одной записи на кластер. Записи в остальном одинаковы, поэтому клиент показывает два сервера с одинаковым именем и ничем их не отличить. ES_INSTANCE_LABEL становится отображаемым заголовком сервера, и это естественное место, чтобы указать, в какое какой окружение попадает запись:

{
  "mcpServers": {
    "es7-prod": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-prod:9200",
        "ES_API_KEY": "prod-key",
        "ES_INSTANCE_LABEL": "production",
        "ES_ADMIN_TOOLS": "true"
      }
    },
    "es7-staging": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-staging:9200",
        "ES_API_KEY": "staging-key",
        "ES_INSTANCE_LABEL": "staging",
        "ES_ADMIN_TOOLS": "true",
        "ES_ALLOW_DESTRUCTIVE": "true"
      }
    }
  }
}

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

Метка также выводится в stderr при запуске — туда стоит смотреть, когда клиент сообщает о подключении, но вы не можете понять, какой кластер ответил.

Конфигурация нескольких URL

Вы можете настроить несколько узлов Elasticsearch для обеспечения высокой доступности и балансировки нагрузки:

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@agrica/elasticsearch7-mcp"
      ],
      "env": {
        "ES_HOST": "https://es-node1:9200,https://es-node2:9200,https://es-node3:9200",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

Клиент автоматически выполнит переключение при сбое и балансировку нагрузки между настроенными узлами.

Запуск Docker

Каждый релиз публикует многоархитектурный образ (linux/amd64, linux/arm64) в GitHub Container Registry:

docker pull ghcr.io/agrica/elasticsearch7-mcp:latest

Сервер общается через stdio, поэтому контейнеру нужны интерактивный stdin и отсутствие опубликованных портов. В MCP-клиенте:

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ES_HOST",
        "-e", "ES_API_KEY",
        "ghcr.io/agrica/elasticsearch7-mcp:latest"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

[!NOTE] Как и npm-пакет, образ находится в GitHub Packages: для его загрузки нужен токен с областью read:packages, даже если репозиторий публичный.

Образу не нужны ни опубликованные порты, ни том: он общается через stdio, а его stdin и stdout принадлежат MCP-клиенту.

Примеры запросов

[!TIP] Ниже приведены несколько запросов на естественном языке, которые вы можете попробовать в своём MCP-клиенте.

Управление кластером

• «Каков статус здоровья моего кластера Elasticsearch?»

• «Сколько активных узлов в моём кластере?»

Операции с индексами

• «Какие индексы есть в моём кластере Elasticsearch?»

• «Создай новый индекс под названием 'users' с 3 шардами и 1 репликой.»

• «Переиндексируй данные из 'old_index' в 'new_index'.»

Управление маппингами

• «Покажи маппинги полей для индекса 'products'.»

• «Добавь поле типа keyword под названием 'tags' в индекс 'products'.»

Поиск и операции с данными

• «Найди все заказы дороже $500 за прошлый месяц.»

• «Какие товары получили больше всего отзывов с 5 звёздами?»

• «Выполни массовый импорт этих записей клиентов в индекс 'customers'.»

Управление шаблонами

• «Создай шаблон индекса для логов с паттерном 'logs-*'.»

• «Покажи все мои шаблоны индексов.»

Диагностика (требуется ES_ADMIN_TOOLS=true)

• «Индекс 'logs-2026' желтый — почему его шарды не назначены?»

• «Близок ли какой-либо узел к порогу disk watermark?»

• «Какой из моих индексов самый большой и сколько в нём удалённых документов?»

• «Отключал ли кто-то распределение шардов на этом кластере?»

• «Переиндексация всё ещё выполняется?»

Деструктивные операции (требуется ES_ALLOW_DESTRUCTIVE=true)

• «Удали индекс 'smoke-test-source'.»

• «Удали из 'logs-archive' все документы старше 2024 года.»

Troublehooting

Нашли ошибку или нужен отсутствующий инструмент? Откройте issue в репозитории GitHub. Чтобы работать над кодом, начните с CONTRIBUTING.md.