Elasticsearch MCP Server
Elasticsearch/OpenSearch MCP Server
Обзор
Реализация сервера 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: Имя пользователя для базовой аутентификации OpenSearchOPENSEARCH_PASSWORD: Пароль для базовой аутентификации OpenSearch
Аутентификация по API-ключу (только Elasticsearch) — рекомендуется
ELASTICSEARCH_API_KEY: API-ключ для аутентификации Elasticsearch или Elastic Cloud.
Настройки подключения
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_indexdelete_index
Операции с документами:
index_documentdelete_documentdelete_by_query
Операции с потоками данных:
create_data_streamdelete_data_stream
Операции с алиасами:
put_aliasdelete_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=gcfstructuredContent сохраняется без изменений, поэтому объявленная схема вывода инструмента по-прежнему проходит проверку, а любой клиент, не использующий модель, продолжает получать JSON; перекодируется только текстовый блок, предназначенный для модели. Кодирование отказоустойчиво: любая ошибка, включая значение за пределами канонического числового домена int64 GCF (который GCF отклоняет, а не молча аппроксимирует), оставляет исходный JSON-результат нетронутым, поэтому вызов инструмента никогда не теряется из-за кодирования. Поведение по умолчанию не меняется, если RESPONSE_FORMAT не задан.
Воспроизведите сравнение токенов: uv run --with tiktoken python benchmarks/gcf_benchmark.py.
Запуск кластера Elasticsearch/OpenSearch
Запустите кластер 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 /sseStreamable 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 toolsanalyze_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
Scored across 20 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseBqualityDmaintenanceConnects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.4Apache 2.0
- FlicenseBqualityDmaintenanceConnects 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-
- AlicenseBqualityDmaintenanceEnables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.1017 npmMIT