Этот репозиторий содержит экспериментальные функции, предназначенные для исследований и оценки и не готовые к использованию в производстве.
Подключитесь к данным Elasticsearch напрямую из любого клиента MCP (например, Claude Desktop) с помощью протокола контекста модели (MCP).
Этот сервер подключает агентов к вашим данным Elasticsearch с помощью Model Context Protocol. Он позволяет вам взаимодействовать с вашими индексами Elasticsearch посредством разговоров на естественном языке.
list_indices : Список всех доступных индексов Elasticsearch
get_mappings : Получить сопоставления полей для определенного индекса Elasticsearch
search : выполнить поиск Elasticsearch с предоставленным запросом DSL
get_shards : Получить информацию о шардах для всех или определенных индексов
Related MCP server: Elasticsearch MCP Server
Экземпляр Elasticsearch
Учетные данные аутентификации Elasticsearch (ключ API или имя пользователя/пароль)
Клиент MCP (например, Claude Desktop)
https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c
[!СОВЕТ] Самый простой способ использовать сервер Elasticsearch MCP — через опубликованный пакет npm.
Настроить MCP-клиент
Откройте ваш MCP Client. Посмотрите список MCP Clients , здесь мы настраиваем Claude Desktop.
Перейдите в Настройки > Разработчик > Серверы MCP.
Нажмите Edit Config и добавьте новый сервер MCP со следующей конфигурацией:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "npx",
"args": [
"-y",
"@elastic/mcp-server-elasticsearch"
],
"env": {
"ES_URL": "your-elasticsearch-url",
"ES_API_KEY": "your-api-key"
}
}
}
}Начать разговор
Откройте новый разговор в вашем MCP Client
Сервер MCP должен подключиться автоматически.
Теперь вы можете задавать вопросы о своих данных Elasticsearch
Сервер Elasticsearch MCP поддерживает параметры конфигурации для подключения к Elasticsearch:
[!ПРИМЕЧАНИЕ] Для аутентификации необходимо предоставить либо ключ API, либо имя пользователя и пароль.
Переменная среды | Описание | Необходимый |
| URL вашего экземпляра Elasticsearch | Да |
| Ключ API Elasticsearch для аутентификации | Нет |
| Имя пользователя Elasticsearch для базовой аутентификации | Нет |
| Пароль Elasticsearch для базовой аутентификации | Нет |
| Путь к пользовательскому сертификату CA для Elasticsearch SSL/TLS | Нет |
[!ПРИМЕЧАНИЕ] Если вы хотите изменить или расширить сервер MCP, следуйте этим шагам локальной разработки.
Используйте правильную версию Node.js
nvm useУстановить зависимости
npm installПостроить проект
npm run buildЗапустить локально в приложении Claude Desktop
Открыть приложение Claude для ПК
Перейдите в Настройки > Разработчик > Серверы MCP.
Нажмите Edit Config и добавьте новый сервер MCP со следующей конфигурацией:
{
"mcpServers": {
"elasticsearch-mcp-server-local": {
"command": "node",
"args": [
"/path/to/your/project/dist/index.js"
],
"env": {
"ES_URL": "your-elasticsearch-url",
"ES_API_KEY": "your-api-key"
}
}
}
}Отладка с помощью MCP Inspector
ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspectorЭто запустит MCP Inspector, позволяющий вам отлаживать и анализировать запросы. Вы должны увидеть:
Starting MCP inspector...
Proxy server listening on port 3000
🔍 MCP Inspector is up and running at http://localhost:5173 🚀Мы приветствуем вклады от сообщества! Подробности о том, как внести вклад, см. в Руководстве по внесению вкладов .
[!СОВЕТ] Вот несколько запросов на естественном языке, которые вы можете попробовать выполнить с помощью своего клиента MCP.
«Какие индексы есть в моем кластере Elasticsearch?»
«Покажите мне сопоставления полей для индекса «продукты»».
«Найти все заказы на сумму более 500 долларов за прошлый месяц».
«Какие продукты получили наибольшее количество 5-звездочных отзывов?»
Клиент MCP анализирует ваш запрос и определяет, какие операции Elasticsearch необходимы.
Сервер MCP выполняет эти операции (перечисление индексов, выборку сопоставлений, выполнение поиска).
Клиент MCP обрабатывает результаты и представляет их в удобном для пользователя формате.
[!WARNING] Избегайте использования привилегий администратора кластера. Создавайте выделенные ключи API с ограниченной областью действия и применяйте детальный контроль доступа на уровне индекса, чтобы предотвратить несанкционированный доступ к данным.
Вы можете создать специальный ключ API Elasticsearch с минимальными правами доступа для управления доступом к вашим данным:
POST /_security/api_key
{
"name": "es-mcp-server-access",
"role_descriptors": {
"mcp_server_role": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"index-1",
"index-2",
"index-pattern-*"
],
"privileges": [
"read",
"view_index_metadata"
]
}
]
}
}
}Данный проект лицензирован по лицензии Apache License 2.0.
Убедитесь, что конфигурация вашего MCP правильная.
Убедитесь, что URL-адрес Elasticsearch доступен с вашего компьютера.
Убедитесь, что ваши учетные данные аутентификации (ключ API или имя пользователя/пароль) имеют необходимые разрешения.
При использовании SSL/TLS с пользовательским центром сертификации убедитесь, что путь к сертификату указан правильно и файл доступен для чтения.
Проверьте вывод терминала на наличие сообщений об ошибках.
Если у вас возникли проблемы, смело сообщайте о них в репозитории GitHub.
Get field mappings for a specific Elasticsearch index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to get mappings for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Get field mappings', implying read-only but not disclosing permissions, side effects, or behavior like error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loaded with the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could mention what the response contains; it is adequate but minimal for a simple get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'index' has a description; the tool description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and resource 'field mappings' for a specific Elasticsearch index, clearly distinguishing from siblings like create_mapping or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; for example, it doesn't explain how it differs from create_mapping or search in terms of use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Elasticsearch indices
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'List' implies a read operation, it doesn't specify whether this requires special permissions, returns paginated results, includes hidden/system indices, or provides any metadata beyond names. For a tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a simple listing tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read operation without output schema, the description provides the minimum viable information about what the tool does. However, given the lack of annotations and sibling tools with potentially overlapping functionality, more context about when to use this versus alternatives would be helpful. The description is complete enough for basic understanding but leaves operational context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't mention parameters since none exist. A baseline of 4 is appropriate for zero-parameter tools where the schema handles all parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all available Elasticsearch indices'), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_mappings' or 'search' - it's unclear if this is a simple listing versus more detailed metadata retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_mappings' or 'search'. There's no indication of whether this is for administrative purposes, discovery, or as a prerequisite for other operations. The agent must infer usage context from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an Elasticsearch search with the provided query DSL. Highlights are always enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to search | |
| queryBody | Yes | Complete Elasticsearch query DSL object that can include query, size, from, sort, etc. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Only mentions highlights are always enabled. No disclosure of read-only nature, error handling, pagination, or required permissions. With no annotations, more behavioral detail is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action. No wasted words, though could be expanded with important behavioral notes without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of Elasticsearch searches (query DSL), the description lacks return format, pagination behavior, and error context. Incomplete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes both parameters. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs an Elasticsearch search with query DSL, identifying the specific verb and resource. Distinguishes from sibling tools that handle index management, bulk operations, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over siblings (e.g., bulk, list_indices) or when not to use it. Lacks prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_mappingslist_indicessearchScored across 3 tools
Each tool has a clearly distinct purpose: get_mappings retrieves field mappings for a specific index, list_indices enumerates all indices, and search performs query-based searches. There is no overlap in functionality, making tool selection unambiguous.
All tool names follow a consistent verb_noun pattern (get_mappings, list_indices, search), with clear and descriptive verbs that align with their actions. No deviations or mixed conventions are present.
With only 3 tools, the set feels thin for an Elasticsearch server, as it lacks essential operations like creating/deleting indices, updating mappings, or performing CRUD operations on documents. While the tools are well-defined, the count is borderline for the domain's scope.
There are significant gaps in the tool surface for Elasticsearch functionality. Missing operations include index creation/deletion, document indexing/updating/deleting, and cluster management. This incompleteness will likely cause agent failures when attempting full workflows.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Connect Claude, Cursor, or ChatGPT to your business data. Ask questions, get answers.
Build and manage AI-native customer support agents from Claude or any MCP client.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
