Elasticsearch MCP Server

Внимание

Этот MCP сервер устарел и будет дальнейшее развитие поддерживаться только с критическими обновлениями безопасности.

Его заменила Elastic Agent Builder MCP endpoint, доступная в Elastic 9.2.0+ и проектах Elasticsearch Serverless.

Использование Elasticsearch MCP Server для агентов ИИ

Elasticsearch MCP Server соединяет ваших агентов ИИ с данными Elasticsearch через Model Context Protocol (MCP).

Это обеспечивает взаимодействие на естественном языке с вашими индексами Elasticsearch: агенты могут запросить, анализировать и извлекать данные без необходимости писать собственные API.

Ниже приведены шаги по развёртыванию и настройке образа контейнера Elasticsearch MCP Server из AWS Marketplace.

Прежде чем начать

Перед началом убедитесь, что у вас есть:

Кластер Elasticsearch (версия 8.x или 9.x), доступный из вашего AWS-окружения
Учётные данные для Elasticsearch:

API-ключ API key, или

Имя пользователя и пароль
Docker установлен и запущен в вашем AWS-окружении (например, на EC2 или в сервисе контейнеризации)
Клиент MCP настроен (например, Claude Desktop, Cursor, VS Code или другой инструмент, совместимый с MCP)
Сетевое соединение между вашей средой развёртывания и кластером Elasticsearch

Примечание

Эти инструкции применяются к Elasticsearch MCP Server 0.4.0 и выше.

Для версий 0.3.1 и ранее смотрите README для v0.3.1.

Развернуть Elasticsearch MCP Server

Elasticsearch MCP Server предоставляется в виде образа Docker-контейнера в AWS Marketplace. Вы можете запустить его с использованием либо протокола stdio (для прямых подключений клиента) либо протокола streamable-HTTP (для веб-интеграций).

Выбор протокола

Сервер поддерживает два протокола:

stdio: прямое взаимодействие между MCP-клиентом и сервером. Используйте, когда ваш клиент поддерживает stdio и работает в той же среде.
streamable-HTTP: протокол на основе HTTP, рекомендуется для веб-интеграций, сессий с сохранением состояния и нескольких одновремённых клиентов.

Примечание: Server-Sent Events (SSE) устарел. Используйте streamable-HTTP.

Настройка протокола stdio

Используйте протокол stdio, когда ваш MCP-клиент напрямую подключается к процессу сервера.

Установка переменных окружения для режима stdio

Установите следующие переменные окружения:

ES_URL: URL вашего кластера Elasticsearch (например, https://your-cluster.es.amazonaws.com:9200)
Для аутентификации используйте один из вариантов:

API key: установите ES_API_KEY своим API-ключом Elasticsearch

Базовая аутентификация: установите ES_USERNAME и ES_PASSWORD для учётных данных Elasticsearch
(Опционально) ES_SSL_SKIP_VERIFY: установите true, чтобы пропустить проверку сертификата SSL/TLS при подключении к Elasticsearch. Используйте только для разработки или тестирования.

Запуск контейнера в режиме stdio

Запустите MCP-сервер в режиме stdio:

docker run -i --rm \
  -e ES_URL \
  -e ES_API_KEY \
  docker.elastic.co/mcp/elasticsearch \
  stdio

Настройка Claude Desktop

Добавьте эту конфигурацию в файл конфигурации Claude Desktop:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ES_URL",
        "-e", "ES_API_KEY",
        "docker.elastic.co/mcp/elasticsearch",
        "stdio"
      ],
      "env": {
        "ES_URL": "<elasticsearch-cluster-url>",
        "ES_API_KEY": "<elasticsearch-API-key>"
      }
    }
  }
}

Замените <elasticsearch-cluster-url> и <elasticsearch-API-key> на реальные значения.

Настройка протокола streamable-HTTP

Используйте протокол streamable-HTTP для веб-интеграций или если требуется поддержка нескольких параллельных клиентов.

Установка переменных окружения для режима HTTP

Установите те же переменные окружения, что и для stdio:

ES_URL: URL вашего кластера Elasticsearch
Для аутентификации используйте один из вариантов:

API key: установите ES_API_KEY своим API-ключом Elasticsearch

Базовая аутентификация: установите ES_USERNAME и ES_PASSWORD
(Опционально) ES_SSL_SKIP_VERIFY: установите true, чтобы пропустить проверку сертификата SSL/TLS

Запуск контейнера в режиме HTTP

docker run --rm \
  -e ES_URL \
  -e ES_API_KEY \
  -p 8080:8080 \
  docker.elastic.co/mcp/elasticsearch \
  http

Точка доступа streamable-HTTP доступна по адресу http://<host>:8080/mcp. Эндпойнт для проверки работоспособности — http://<host>:8080/ping.

Настройка Claude Desktop с HTTP-прокси

Если вы используете Claude Desktop (free edition), который поддерживает только протокол stdio, используйте mcp-proxy для моста stdio в streamable-HTTP:

Установка mcp-proxy:

uv tool install mcp-proxy

В качестве альтернативы см. mcp-proxy/README.md.
Добавьте следующую конфигурацию в Claude Desktop:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "/<home-directory>/.local/bin/mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "--header", "Authorization", "ApiKey <elasticsearch-API-key>",
        "http://<mcp-server-host>:<mcp-server-port>/mcp"
      ]
    }
  }
}

Замените <home-directory>, <elasticsearch-API-key>, <mcp-server-host> и <mcp-server-port> на реальные значения.

Проверка соединения

После настройки MCP-клиента проверьте, что соединение работает:

Запустите ваш MCP-клиент (например, Claude Desktop или Cursor).
Убедитесь, что Elasticsearch MCP Server отображается в списке доступных MCP-серверов.
Протестируйте простой запрос через интерфейс вашего агента, чтобы проверить доступ к индексам Elasticsearch.

Если соединение не удаётся установить, проверьте:

Правильность URL вашего кластера Elasticsearch и доступность из вашего AWS-окружения
Валидность учётных данных и наличие необходимых прав
Наличие сетевого соединения между контейнером и кластером Elasticsearch (проверьте группы безопасности и сетевые ACL)
Работа Docker и успешный запуск контейнера (проверяйте логи контейнера через docker logs <container-id>)

Мониторинг работоспособности и статуса

Отслеживайте состояние и корректную работу Elasticsearch MCP Server следующими способами:

Проверка статуса контейнера

Убедитесь, что контейнер запущен:

docker ps | grep elasticsearch-mcp-server

Контейнер должен отображаться в списке со статусом Up.

Тестирование health-эндпойнта (HTTP-режим)

Если используется протокол streamable-HTTP, протестируйте health-check эндпойнт:

curl http://<host>:8080/ping

Успешный ответ должен быть pong, что означает, что сервер работает и доступен.

Просмотр логов контейнера

Просмотрите логи контейнера для выявления возможных проблем:

docker logs <container-id>

Ищите сообщения об ошибках, связанных с:

Ошибками подключения к Elasticsearch
Ошибками аутентификации
Проблемами сетевого соединения

Проверка доступности Elasticsearch из контейнера

Проверьте соединение с кластером Elasticsearch из контейнера:

docker exec <container-id> curl -k -u <username>:<password> <ES_URL>

Или с использованием API-ключа:

docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>

Успешный ответ означает, что контейнер может достигнуть ваш кластер Elasticsearch.

Безопасность и конфиденциальная информация

Elasticsearch MCP Server надёжно обрабатывает учётные данные:

Хранение учётных данных

API-ключи и пароли: хранятся только в переменных окружения, переданных в контейнер. Они не сохраняются на диске и не логируются.
Переменные окружения: устанавливаются при запуске контейнера. В продакшн-средах используйте AWS Secrets Manager или AWS Systems Manager Parameter Store для безопасного управления учётными данными.

Шифрование данных

В транзите: MCP-сервер общается с Elasticsearch через HTTPS, если ваш ES_URL использует протокол https://. Убедитесь, что в кластере Elasticsearch включено SSL/TLS.
В состоянии покоя: контейнер не хранит данные локально. Все данные остаются в вашем кластере Elasticsearch, который использует настройки шифрования вашего кластера.

Лучшие практики

Регулярно вращайте API-ключи (например, каждые 30–90 дней в продакшн-среде)
Используйте API-ключи с минимально необходимыми правами (например, только чтение для конкретных индексов)
Никогда не сохраняйте учётные данные в системах контроля версий и не публикуйте их в логах
Используйте AWS Secrets Manager или Parameter Store для внедрения учётных данных во время выполнения, вместо хардкодирования

Квоты сервисов AWS

Elasticsearch MCP Server разворачивается как контейнер в вашей AWS-среде. Учтите следующие квоты AWS:

Лимиты инстансов EC2: если вы запускаете на EC2, убедитесь, что тип инстанса соответствует ожидаемой нагрузке
Elastic Container Service (ECS): если используете ECS, ознакомьтесь с ECS service quotas
Elastic Kubernetes Service (EKS): если используете EKS, ознакомьтесь с EKS service quotas
Сетевой трафик: обеспечьте достаточную пропускную способность между контейнером и кластером Elasticsearch

Чтобы запросить увеличение квот, используйте консоль AWS Service Quotas или руководство AWS General Reference Guide.

Доступные инструменты

После подключения MCP-сервер предоставляет вашему агенту следующие инструменты:

list_indices: перечислить все доступные индексы Elasticsearch
get_mappings: получить отображения полей для конкретного индекса Elasticsearch
search: выполнить поиск Elasticsearch с использованием DSL
esql: выполнить запрос ES|QL
get_shards: получить информацию о шардах для всех или определённых индексов

Ваш агент может использовать эти инструменты для взаимодействия с данными Elasticsearch в рамках естественного языка.

Дальнейшие шаги

Узнайте о функциональности на основе искусственного интеллекта, доступной в платформе Elastic
Изучите Agent Builder для создания пользовательских агентов ИИ с Elasticsearch