Skip to main content
Glama
Elasticsearch MCP Server

Elasticsearch MCP Server

Elasticsearch/OpenSearch MCP Server

Trust Score

Обзор

Реализация сервера Model Context Protocol (MCP), обеспечивающая взаимодействие с Elasticsearch и OpenSearch. Этот сервер позволяет искать документы, анализировать индексы и управлять кластером с помощью набора инструментов.

Related MCP server: Elasticsearch MCP Server

Демонстрация

https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15

Возможности

Общие операции

  • general_api_request: Выполнить общий HTTP API-запрос. Используйте этот инструмент для любого API Elasticsearch/OpenSearch, для которого нет специального инструмента.

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

  • list_indices: Список всех индексов.

  • get_index: Возвращает информацию (mappings, settings, aliases) об одном или нескольких индексах.

  • create_index: Создать новый индекс.

  • delete_index: Удалить индекс.

  • create_data_stream: Создать новый поток данных (требуется соответствующий шаблон индекса).

  • get_data_stream: Получить информацию об одном или нескольких потоках данных.

  • delete_data_stream: Удалить один или несколько потоков данных и их резервные индексы.

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

  • search_documents: Поиск документов.

  • index_document: Создает или обновляет документ в индексе.

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

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

  • delete_by_query: Удаляет документы, соответствующие заданному запросу.

Операции с кластером

  • get_cluster_health: Возвращает базовую информацию о состоянии кластера.

  • get_cluster_stats: Возвращает общий обзор статистики кластера.

Операции с алиасами

  • list_aliases: Список всех алиасов.

  • get_alias: Получить информацию об алиасе для конкретного индекса.

  • put_alias: Создать или обновить алиас для конкретного индекса.

  • delete_alias: Удалить алиас для конкретного индекса.

Операции с анализаторами

  • analyze_text: Анализ текста с использованием указанного анализатора или пользовательской цепочки анализа. Полезно для отладки поисковых запросов и понимания того, как текст токенизируется.

Настройка переменных окружения

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

Базовая аутентификация (имя пользователя/пароль)

  • ELASTICSEARCH_USERNAME: Имя пользователя для базовой аутентификации

  • ELASTICSEARCH_PASSWORD: Пароль для базовой аутентификации

  • OPENSEARCH_USERNAME: Имя пользователя для базовой аутентификации OpenSearch

  • OPENSEARCH_PASSWORD: Пароль для базовой аутентификации OpenSearch

Аутентификация по API-ключу (только Elasticsearch) — рекомендуется

Настройки подключения

  • ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: Список хостов через запятую (по умолчанию: https://localhost:9200)

  • ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS: Встроенный JSON-объект для конфигурации именованных кластеров. При установке инструменты могут нацеливаться на конкретный кластер с помощью необязательного параметра cluster.

  • ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE: Путь к JSON-файлу с объектом кластеров. Рекомендуется, когда конфигурация встроена в другой JSON-файл (например, в конфигурацию MCP-клиента), поскольку это позволяет избежать экранирования JSON-в-JSON. Имеет приоритет над встроенной переменной, если заданы обе.

  • DEFAULT_CLUSTER: Имя кластера по умолчанию, используемое при настройке нескольких кластеров, если в вызове инструмента опущен параметр cluster (по умолчанию используется первый настроенный кластер).

  • VERIFY_CERTS: Проверять ли SSL-сертификаты (по умолчанию: false)

  • REQUEST_TIMEOUT: Тайм-аут запроса в секундах (необязательно, если не задан, используется значение по умолчанию клиента)

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

По умолчанию сервер использует один кластер Elasticsearch из ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD и ELASTICSEARCH_API_KEY, или один кластер OpenSearch из OPENSEARCH_HOSTS, OPENSEARCH_USERNAME и OPENSEARCH_PASSWORD. Чтобы настроить несколько именованных кластеров, задайте ELASTICSEARCH_CLUSTERS (или OPENSEARCH_CLUSTERS) как JSON-объект внутри конфигурации MCP-сервера. Поскольку значение представляет собой JSON-строку, встроенную в другой JSON-файл, внутренние кавычки необходимо экранировать:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_CLUSTERS": "{\"prod\": {\"hosts\": [\"https://prod-es:9200\"], \"api_key\": \"<PROD_API_KEY>\", \"verify_certs\": true}, \"staging\": {\"hosts\": [\"https://staging-es:9200\"], \"username\": \"elastic\", \"password\": \"<STAGING_PASSWORD>\"}}",
        "DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

Для лучшей читаемости укажите ELASTICSEARCH_CLUSTERS_FILE (или OPENSEARCH_CLUSTERS_FILE) на отдельный JSON-файл. Значение — просто путь, что позволяет избежать экранирования JSON-в-JSON:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_CLUSTERS_FILE": "/etc/mcp/es-clusters.json",
        "DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

/etc/mcp/es-clusters.json:

{
  "prod": {
    "hosts": ["https://prod-es:9200"],
    "api_key": "<PROD_API_KEY>",
    "verify_certs": true
  },
  "staging": {
    "hosts": ["https://staging-es:9200"],
    "username": "elastic",
    "password": "<STAGING_PASSWORD>"
  }
}

Каждый инструмент принимает необязательный параметр cluster. Если он опущен, сервер использует DEFAULT_CLUSTER. Если DEFAULT_CLUSTER не задан, по умолчанию используется первый кластер в JSON-объекте. Вызов инструмента, нацеленный на конкретный кластер, выглядит так:

{
  "cluster": "staging",
  "index": "logs-*",
  "body": {
    "query": {
      "match_all": {}
    }
  }
}

Аутентификация MCP-сервера (только HTTP-транспорты)

При запуске MCP-сервера с HTTP-транспортами (SSE или Streamable HTTP) вы можете включить аутентификацию по Bearer-токену для защиты сервера от несанкционированного доступа.

  • MCP_API_KEY: API-ключ для аутентификации MCP-сервера. Клиенты должны включать заголовок Authorization: Bearer <MCP_API_KEY>.

Важные замечания по безопасности:

  • Аутентификация применима только для HTTP-транспортов (sse, streamable-http). Транспорт stdio использует локальную межпроцессную связь и не требует аутентификации.

  • Если MCP_API_KEY не задан, MCP-сервер будет доступен без аутентификации. Это риск для безопасности при развертывании сервера в сети.

  • Для производственных развертываний с HTTP-транспортами всегда задавайте MCP_API_KEY.

# Generate a secure API key (example using openssl)
export MCP_API_KEY=$(openssl rand -base64 32)

# Or set a custom API key
export MCP_API_KEY="your-secure-api-key-here"

Отключение операций с высоким риском

  • DISABLE_HIGH_RISK_OPERATIONS: Установите true, чтобы отключить все операции записи (по умолчанию: false)

  • DISABLE_OPERATIONS: Список конкретных операций для отключения через запятую (необязательно, если не задан, используется список операций записи по умолчанию)

Когда DISABLE_HIGH_RISK_OPERATIONS установлен в true, все MCP-инструменты, выполняющие операции записи, полностью скрыты от MCP-клиента. В этом режиме по умолчанию отключены следующие MCP-инструменты.

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

    • create_index

    • delete_index

  • Операции с документами:

    • index_document

    • delete_document

    • delete_by_query

  • Операции с потоками данных:

    • create_data_stream

    • delete_data_stream

  • Операции с алиасами:

    • put_alias

    • delete_alias

  • Общие API-операции:

    • general_api_request

При желании вы можете указать список операций для отключения через запятую в переменной окружения DISABLE_OPERATIONS.

# Disable High-Risk Operations
export DISABLE_HIGH_RISK_OPERATIONS=true
# Disable specific operations only
export DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"

Кодирование ответов GCF (необязательно)

Включите сериализацию полезных нагрузок результатов инструментов в GCF (Graph Compact Format) — оптимизированный по токенам формат передачи данных — в блоке содержимого, который читает модель. Elasticsearch возвращает большие однородные наборы записей (результаты поиска, корзины агрегаций, mappings) — именно ту форму, которую GCF сжимает лучше всего: на репрезентативных ответах это ~39% меньше токенов, чем компактный JSON (40% на результатах поиска), без потерь.

export RESPONSE_FORMAT=gcf

structuredContent сохраняется без изменений, поэтому объявленная схема вывода инструмента по-прежнему проходит проверку, а любой клиент, не использующий модель, продолжает получать JSON; перекодируется только текстовый блок, предназначенный для модели. Кодирование отказоустойчиво: любая ошибка, включая значение за пределами канонического числового домена int64 GCF (который GCF отклоняет, а не молча аппроксимирует), оставляет исходный JSON-результат нетронутым, поэтому вызов инструмента никогда не теряется из-за кодирования. Поведение по умолчанию не меняется, если RESPONSE_FORMAT не задан.

Воспроизведите сравнение токенов: uv run --with tiktoken python benchmarks/gcf_benchmark.py.

Запустите кластер Elasticsearch/OpenSearch с помощью Docker Compose:

# For Elasticsearch
docker-compose -f docker-compose-elasticsearch.yml up -d

# For OpenSearch
docker-compose -f docker-compose-opensearch.yml up -d

Имя пользователя Elasticsearch по умолчанию — elastic, пароль — test123. Имя пользователя OpenSearch по умолчанию — admin, пароль — admin.

Вы можете получить доступ к Kibana/OpenSearch Dashboards по адресу http://localhost:5601.

Stdio

Вариант 1: Использование uvx

Использование uvx автоматически установит пакет из PyPI, нет необходимости клонировать репозиторий локально. Добавьте следующую конфигурацию в файл конфигурации claude_desktop_config.json.

// For Elasticsearch with username/password
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// For Elasticsearch with API key
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
      }
    }
  }
}

// For OpenSearch
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": [
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

Вариант 2: Использование uv с локальной разработкой

Использование uv требует клонирования репозитория локально и указания пути к исходному коду. Добавьте следующую конфигурацию в файл конфигурации Claude Desktop claude_desktop_config.json.

// For Elasticsearch with username/password
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// For Elasticsearch with API key
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
      }
    }
  }
}

// For OpenSearch
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

SSE

Вариант 1: Использование uvx

# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uvx elasticsearch-mcp-server --transport sse

# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Вариант 2: Использование uv

# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uv run src/server.py elasticsearch-mcp-server --transport sse

# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Streamable HTTP

Вариант 1: Использование uvx

# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uvx elasticsearch-mcp-server --transport streamable-http

# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Вариант 2: Использование uv

# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uv run src/server.py elasticsearch-mcp-server --transport streamable-http

# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Совместимость

MCP-сервер совместим с Elasticsearch 7.x, 8.x и 9.x. По умолчанию используется клиент Elasticsearch 8.x (без суффикса).

MCP Server

Elasticsearch

elasticsearch-mcp-server-es7

Elasticsearch 7.x

elasticsearch-mcp-server

Elasticsearch 8.x

elasticsearch-mcp-server-es9

Elasticsearch 9.x

opensearch-mcp-server

OpenSearch 1.x, 2.x, 3.x

Чтобы использовать клиент Elasticsearch 7.x, запустите вариант elasticsearch-mcp-server-es7. Для Elasticsearch 9.x используйте elasticsearch-mcp-server-es9. Например:

uvx elasticsearch-mcp-server-es7

Если вы хотите запускать различные варианты Elasticsearch (например, 7.x или 9.x) локально, просто обновите зависимость elasticsearch в pyproject.toml, затем запустите сервер с помощью:

uv run src/server.py elasticsearch-mcp-server

Развертывание в Kubernetes

Docker-образ публикуется в ghcr.io/cr7258/elasticsearch-mcp-server, а Helm-чарт доступен как OCI-артефакт в репозитории oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server.

Полные инструкции по установке, справочник по конфигурации и примеры использования см. в README Helm-чарта.

Лицензия

Этот проект лицензирован в соответствии с Apache License Version 2.0 — подробности см. в файле LICENSE.

Available Tools

20 tools
analyze_textB

Analyze text to see how it would be tokenized.

Use this tool to understand how Elasticsearch/OpenSearch tokenizes and transforms text using analyzers. This is essential for debugging search queries and understanding why certain documents match or don't match.

Inputs: text (required), index, filter, cluster, +5 more. Returns: object

create_data_streamB

Create a new data stream.

This creates a new data stream with the specified name. The data stream must have a matching index template before creation.

Inputs: name (required), cluster. Returns: object

create_indexC

Create a new index.

Inputs: index (required), body, cluster. Returns: object

delete_aliasC

Delete an alias for a specific index.

Inputs: name (required), index (required), cluster. Returns: object

delete_by_queryC

Deletes documents matching the provided query.

Inputs: body (required), index (required), cluster. Returns: object

delete_data_streamA

Delete one or more data streams.

Permanently deletes the specified data streams and all their backing indices.

Inputs: name (required), cluster. Returns: object

delete_documentC

Delete a document by ID.

Inputs: id (required), index (required), cluster. Returns: object

delete_indexC

Delete an index.

Inputs: index (required), cluster. Returns: object

general_api_requestA

Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.

Inputs: path (required), method (required), body, params, +1 more.

get_aliasC

Get alias information for a specific index.

Inputs: index (required), cluster. Returns: object

get_cluster_healthC

Returns basic information about the health of the cluster.

Inputs: cluster. Returns: object

get_cluster_statsB

Returns high-level overview of cluster statistics.

Inputs: cluster. Returns: object

get_data_streamC

Get information about one or more data streams.

Retrieves configuration, mappings, settings, and other information about the specified data streams.

Inputs: name, cluster. Returns: object

get_documentC

Get a document by ID.

Inputs: id (required), index (required), cluster. Returns: object

get_indexB

Returns information (mappings, settings, aliases) about one or more indices.

Inputs: index (required), cluster. Returns: object

index_documentC

Creates or updates a document in the index.

Inputs: index (required), document (required), id, cluster. Returns: object

list_aliasesB

List all aliases.

Inputs: cluster. Returns: result

list_indicesC

List all indices.

Inputs: cluster. Returns: result

put_aliasC

Create or update an alias for a specific index.

Inputs: body (required), name (required), index (required), cluster. Returns: object

search_documentsC

Search for documents.

Inputs: body (required), index (required), cluster. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource and action (index, document, alias, data stream, cluster, analysis, or generic API). Overlaps like get_index vs list_indices and get_alias vs list_aliases are cleanly separated by specificity. The general_api_request fallback is explicitly scoped to APIs without dedicated tools, so it does not create real misselection risk.

    Naming Consistency5/5

    Tools follow a consistent snake_case verb_noun convention (create_index, delete_document, get_cluster_health, put_alias, etc.). The only minor exception is general_api_request, but it still fits the overall readable naming style. There is no mixing of camelCase or conflicting verb patterns.

    Tool Count4/5

    At 20 tools, the surface is slightly heavy by the usual 3–15 guideline, but Elasticsearch is a broad domain and each tool covers a meaningful resource area. The set avoids extreme bloat and does not include redundant operations.

    Completeness4/5

    Core CRUD and lifecycle coverage exists for indices, documents, aliases, data streams, and cluster inspection, with search and text analysis included. Notable gaps remain—such as dedicated index template management (required for data streams), bulk operations, and update-by-query—but the general_api_request tool provides a workaround for any missing API.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLMs to interact with Elasticsearch clusters, allowing them to manage indices and execute search queries using natural language.
      2
      -
    • A
      license
      B
      quality
      D
      maintenance
      Connects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.
      4
      Apache 2.0
    • F
      license
      B
      quality
      D
      maintenance
      Connects to Elasticsearch clusters through the Model Context Protocol, enabling natural language querying and management of Elasticsearch data. Provides tools to search indices, list available indices, and retrieve index mappings.
      3
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.
      10
      17 npm
      MIT