Elasticsearch

Conecte-se e interaja com um cluster Elasticsearch diretamente de qualquer cliente MCP usando variáveis de ambiente para configuração.

GitHub

Documentação

Elasticsearch MCP Server

English | 中文

Servidor MCP para conectar-se ao seu cluster Elasticsearch diretamente de qualquer Cliente MCP (como Claude Desktop, Cursor).

Este servidor conecta agentes aos seus dados do Elasticsearch usando o Model Context Protocol. Ele permite que você interaja com seus índices do Elasticsearch por meio de conversas em linguagem natural.

Demo

Visão Geral dos Recursos

Recursos Disponíveis

Gerenciamento de Cluster

elasticsearch_health: Obtenha o status de saúde do cluster Elasticsearch, opcionalmente incluindo detalhes no nível do índice

Operações de Índice

list_indices: Liste os índices Elasticsearch disponíveis, com suporte a regex
create_index: Crie um índice Elasticsearch com configurações e mapeamentos opcionais
reindex: Reindexe dados de um índice de origem para um índice de destino com consulta e script opcionais

Gerenciamento de Mapeamentos

get_mappings: Obtenha os mapeamentos de campos para um índice Elasticsearch específico
create_mapping: Crie ou atualize a estrutura de mapeamento para um índice Elasticsearch

Operações de Pesquisa e Dados

search: Execute uma pesquisa no Elasticsearch com o query DSL fornecido
bulk: Importe dados em massa para um índice Elasticsearch

Gerenciamento de Modelos (Templates)

create_index_template: Crie ou atualize um modelo de índice
get_index_template: Obtenha informações sobre modelos de índice
delete_index_template: Exclua um modelo de índice

Como Funciona

O Cliente MCP analisa sua solicitação e determina quais operações do Elasticsearch são necessárias.
O servidor MCP executa essas operações (listar índices, buscar mapeamentos, realizar pesquisas).
O Cliente MCP processa os resultados e os apresenta em um formato amigável ao usuário.

Primeiros Passos

Pré-requisitos

Uma instância do Elasticsearch
Credenciais de autenticação do Elasticsearch (API key ou nome de usuário/senha)
Cliente MCP (ex.: Claude Desktop, Cursor)

Instalação e Configuração

Usando o Pacote NPM Publicado

[!TIP] A maneira mais fácil de usar o Elasticsearch MCP Server é através do pacote npm publicado.

Configure o Cliente MCP

Abra seu Cliente MCP. Consulte a lista de Clientes MCP, aqui estamos configurando o Claude Desktop.
Vá para Configurações > Desenvolvedor > Servidores MCP
Clique em Edit Config e adicione um novo Servidor MCP com a seguinte configuração:

{
  "mcpServers": {
    "elasticsearch-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@awesome-ai/elasticsearch-mcp"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

Inicie uma Conversa
- Abra uma nova conversa no seu Cliente MCP.
- O servidor MCP deve conectar automaticamente.
- Agora você pode fazer perguntas sobre seus dados do Elasticsearch.

Opções de Configuração

O Elasticsearch MCP Server suporta opções de configuração para conectar-se ao seu Elasticsearch:

[!NOTE] Você deve fornecer uma API key ou nome de usuário e senha para autenticação.

Variável de Ambiente	Descrição	Obrigatória
`ES_HOST`	URL(s) da sua instância Elasticsearch - suporta URL única ou múltiplas URLs separadas por vírgula (também suporta o legado `HOST`)	Sim
`ES_API_KEY`	API key do Elasticsearch para autenticação (também suporta o legado `API_KEY`)	Não
`ES_USERNAME`	Nome de usuário do Elasticsearch para autenticação básica (também suporta o legado `USERNAME`)	Não
`ES_PASSWORD`	Senha do Elasticsearch para autenticação básica (também suporta o legado `PASSWORD`)	Não
`ES_CA_CERT`	Caminho para certificado CA personalizado para SSL/TLS do Elasticsearch (também suporta o legado `CA_CERT`)	Não

Configuração de Múltiplas URLs

Você pode configurar vários nós Elasticsearch para alta disponibilidade e balanceamento de carga:

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

O cliente lidará automaticamente com failover e balanceamento de carga entre os nós configurados.

Desenvolvimento Local

[!NOTE] Se você quiser modificar ou estender o Servidor MCP, siga estas etapas de desenvolvimento local.

Use a versão correta do Node.js
```
nvm use
```
Instale as Dependências
```
npm install
```
Compile o Projeto
```
npm run build
```

Execute localmente no Claude Desktop App

Abra o Claude Desktop App
Vá para Configurações > Desenvolvedor > Servidores MCP
Clique em Edit Config e adicione um novo Servidor MCP com a seguinte configuração:

{
  "mcpServers": {
    "elasticsearch-mcp": {
      "command": "node",
      "args": [
        "/path/to/your/project/dist/index.js"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

Execute localmente no Cursor Editor

Abra o Cursor Editor
Vá para Configurações do Cursor > MCP
Clique em Add new global MCP Server e adicione um novo Servidor MCP com a seguinte configuração:

{
  "mcpServers": {
    "elasticsearch-mcp": {
      "command": "node",
      "args": [
        "/path/to/your/project/dist/index.js"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

Depuração com o MCP Inspector

ES_HOST=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspector

Isso iniciará o MCP Inspector, permitindo que você depure e analise solicitações. Você deverá ver:

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

Exemplos de Consultas

[!TIP] Aqui estão algumas consultas em linguagem natural que você pode experimentar com seu Cliente MCP.

Gerenciamento de Cluster

"Qual é o status de saúde do meu cluster Elasticsearch?"
"Quantos nós ativos existem no meu cluster?"

Operações de Índice

"Quais índices tenho no meu cluster Elasticsearch?"
"Crie um novo índice chamado 'users' com 3 shards e 1 réplica."
"Reindexe dados de 'old_index' para 'new_index'."

Gerenciamento de Mapeamentos

"Mostre-me os mapeamentos de campos para o índice 'products'."
"Adicione um campo do tipo keyword chamado 'tags' ao índice 'products'."

Operações de Pesquisa e Dados

"Encontre todos os pedidos acima de $500 do mês passado."
"Quais produtos receberam mais avaliações de 5 estrelas?"
"Importe em massa estes registros de clientes para o índice 'customers'."

Gerenciamento de Modelos (Templates)

"Crie um modelo de índice para logs com o padrão 'logs-*'."
"Mostre-me todos os meus modelos de índice."
"Exclua o modelo de índice 'outdated_template'."

Se você encontrar problemas, sinta-se à vontade para abrir uma issue no repositório do GitHub.