Elasticsearch Security Solution

Um servidor Elasticsearch focado em segurança e análise de ameaças. Requer uma licença válida do Elasticsearch (trial, platinum ou enterprise) para conexão.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP do Elasticsearch

Solução aprimorada do servidor MCP do Elasticsearch - Foco em segurança e análise de ameaças

Esta é uma solução profissional focada em segurança, mantida pela TocharianOU. Ela permite interação abrangente com todas as APIs do Elasticsearch, especificamente otimizada para análise de segurança, detecção de ameaças e investigação de incidentes. Os recursos incluem monitoramento avançado de segurança, detecção de anomalias, caça a ameaças, análise de causa raiz e recursos abrangentes de auditoria.

Principais recursos de segurança:

Detecção de ameaças em tempo real e monitoramento de segurança
Aprendizado de máquina avançado para detecção de anomalias
Análise de causa raiz e rastreamento de cadeia de ataques
Investigação de incidentes de segurança e perícia digital
Monitoramento de conformidade e relatórios de auditoria

Observação: Esta solução foi projetada para profissionais de segurança, equipes de SOC e analistas de ameaças.

Conecte-se aos seus dados do Elasticsearch diretamente de qualquer cliente MCP (como o Claude Desktop) usando o Model Context Protocol (MCP). Interaja com seus dados de segurança do Elasticsearch por meio de consultas em linguagem natural para análise avançada de ameaças e resposta a incidentes.

Pré-requisitos

Uma instância do Elasticsearch
Credenciais de autenticação do Elasticsearch (chave de API ou nome de usuário/senha)
Cliente MCP (ex.: Claude Desktop) ou cliente HTTP para acesso remoto

Suporte a múltiplas versões do Elasticsearch

Suporta automaticamente Elasticsearch 5.x - 9.x com detecção inteligente de versão:

Versão	Status	Cliente	Observações
ES 5.x	✅	5.6.22	EOL - Apenas ferramentas básicas
ES 6.x	✅	6.8.8	EOL - ILM disponível (6.6+)
ES 7.x	✅	7.17.14	LTS - Recursos completos
ES 8.x	✅	8.19.1	Recomendado - Recursos mais recentes, ES\|QL (8.11+)
ES 9.x+	✅	Fallback automático	Pronto para o futuro

Principais recursos:

Detecção automática de versão - Nenhuma configuração manual necessária
Seleção inteligente de cliente - Carrega o cliente certo para a sua versão do ES
Recursos adaptativos - Desativa ferramentas não suportadas (ex.: Data Streams no ES < 7.9, ES|QL no ES < 8.11)
Otimizações específicas de versão - Lida com diferenças de API de forma transparente

O que acontece:

Connect → Detect ES version → Load matching client → Register compatible tools

O Query Harness (v0.9.0)

Desde a v0.9.0, o servidor inclui um query harness: uma camada determinística entre o modelo de IA e o seu cluster. A filosofia de design é simples:

O modelo dirige; o harness conhece. A intenção ("encontrar logins falhos por usuário") pertence ao modelo. A correção (nomes reais de campos, capacidade de agregação, peculiaridades de versão) pertence ao harness.

O que isso significa na prática — no nível dos princípios, não dos detalhes internos:

A verdade ao vivo supera o conhecimento empacotado, que supera a memória do modelo. Cada consulta é verificada contra as capacidades reais de campos do cluster antes de ser executada. Um vocabulário ECS (Elastic Common Schema) empacotado fornece significado; o cluster ao vivo fornece existência. A memória do próprio modelo nunca é confiável.
Erros inequívocos são corrigidos silenciosamente; os ambíguos se tornam orientação. O exemplo clássico: um sufixo .keyword espúrio em mapeamentos ECS modernos é corrigido automaticamente (e a correção é relatada); um campo desconhecido bloqueia a consulta condenada e retorna os campos reais mais próximos em vez de um erro do provedor.
O conhecimento de campos fica fora da janela de contexto. O dicionário ECS completo (milhares de campos) vive na memória do processo. O modelo recupera apenas os poucos que precisa, sob demanda, via lookup_fields.
Cada falha deve ser acionável. Erros brutos do Elasticsearch são reescritos com sugestões ao vivo e conselhos de nomenclatura de índices (data stream vs. nomenclatura legada do Beats, índices internos que devem ser acessados via APIs do Kibana, e assim por diante).
O modelo precisa de zero conhecimento de versão. Eras de nomenclatura, diferenças de API e diferenças de estilo de mapeamento (subcampo legado text + .keyword vs. keyword simples moderno) são absorvidos inteiramente pelo harness. O mesmo modelo se comporta de forma idêntica contra ES 5.6 e ES 9.x — verificado por uma matriz de testes de versão cobrindo nove versões marcantes (5.6 → 9.0).
Uma saída de emergência sempre existe. A validação pode ser ignorada por chamada (skip_lint) quando o modelo sabe mais — ex.: campos de runtime definidos fora da consulta. O harness auxilia; nunca aprisiona.

Conexão SSL/TLS

Para conectar ao Elasticsearch com um certificado autoassinado ou em um ambiente de teste, você pode definir a seguinte variável de ambiente:

NODE_TLS_REJECT_UNAUTHORIZED=0

⚠️ Isso desativa a validação de certificado SSL do Node.js. Use apenas em ambientes de desenvolvimento ou teste. Para produção, use sempre um certificado CA confiável.

Instalação e Configuração

Instale (ou execute) o servidor, aponte-o para o seu cluster via variáveis de ambiente, registre-o no seu cliente MCP e então basta iniciar uma conversa — o servidor conecta e registra as ferramentas que a sua versão do ES suporta.

Opções de Configuração

O servidor MCP do Elasticsearch suporta as seguintes opções de configuração:

Configuração do Elasticsearch

Variável de Ambiente	Descrição	Obrigatório
`ES_URL`	URL da sua instância do Elasticsearch	Sim
`ES_API_KEY`	Chave de API do Elasticsearch para autenticação	Não
`ES_USERNAME`	Nome de usuário do Elasticsearch para autenticação básica	Não
`ES_PASSWORD`	Senha do Elasticsearch para autenticação básica	Não
`ES_CA_CERT`	Caminho para certificado CA personalizado para SSL/TLS do Elasticsearch	Não
`NODE_TLS_REJECT_UNAUTHORIZED`	Defina como `0` para desativar a validação de certificado SSL	Não

Configuração do Modo de Transporte (NOVO na v0.3.0)

Variável de Ambiente	Descrição	Padrão	Valores
`MCP_TRANSPORT`	Seleção do modo de transporte	`stdio`	`stdio`, `http`
`MCP_HTTP_PORT`	Porta do servidor HTTP (ao usar transporte HTTP)	`3000`	1-65535
`MCP_HTTP_HOST`	Host do servidor HTTP (ao usar transporte HTTP)	`localhost`	Qualquer host válido

Detalhes do Modo de Transporte:

Modo Stdio (padrão): Para Claude Desktop e clientes MCP locais
Modo HTTP Streamable: Executa como um servidor HTTP autônomo para acesso remoto, integração de API e aplicações web

Início Rápido

Opção 1: Instalação via NPM (Recomendado)

Instale globalmente via NPM

npm install -g @tocharianou/elasticsearch-mcp

Execute diretamente
```
npx @tocharianou/elasticsearch-mcp
```

Opção 2: Release do GitHub (Pacote Autônomo)

Baixe o pacote do release
- Acesse GitHub Releases
- Baixe o arquivo .tar.gz mais recente e seus arquivos de soma de verificação (.sha256 e .sha512)

Verifique a integridade do pacote

shasum -a 256 -c elasticsearch-mcp-v*.tar.gz.sha256
# Should output: elasticsearch-mcp-v*.tar.gz: OK

Extraia e use

mkdir elasticsearch-mcp && cd elasticsearch-mcp
tar -xzf ../elasticsearch-mcp-v*.tar.gz

# Run with your Elasticsearch credentials
ES_URL=https://localhost:9200 ES_API_KEY=your-key node dist/index.js

Opção 3: Instalação a partir do Código-Fonte

Clone o repositório

git clone https://github.com/TocharianOU/elasticsearch-mcp.git
cd elasticsearch-mcp

Instale as dependências
```
npm install
```
Compile o projeto
```
npm run build
```

Configure o aplicativo Claude Desktop

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

Para instalação via NPM:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "npx",
      "args": [
        "@tocharianou/elasticsearch-mcp"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your_pass",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Para instalação a partir do código-fonte:

{
  "mcpServers": {
    "elasticsearch-mcp-server-local": {
      "command": "node",
      "args": [
        "/path/to/your/elasticsearch-mcp/dist/index.js"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your_pass",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Depuração com o MCP Inspector (opcional)

ES_URL=your-elasticsearch-url ES_USERNAME=elastic ES_PASSWORD=your_pass npm run inspector

Notas de Instalação e Integração

Se o npm install -g se comportar mal:

Erros de permissão (EACCES) na instalação global — não use sudo. Ou pule a instalação global completamente e deixe o seu cliente MCP executar npx @tocharianou/elasticsearch-mcp (o npx busca sob demanda), ou defina um prefixo no nível do usuário: npm config set prefix ~/.npm-global e adicione-o ao seu PATH.
Registro lento ou bloqueado — use um espelho apenas para a instalação: npm install -g @tocharianou/elasticsearch-mcp --registry=https://registry.npmmirror.com.
Versão do Node — requer Node 18+ (node --version). Node mais antigo falha na inicialização com erros de ESM/fetch, não no momento da instalação.
Cold start do npx — a primeira execução do npx baixa o pacote; se o seu cliente MCP expirar na primeira conexão, execute npx @tocharianou/elasticsearch-mcp uma vez em um terminal para aquecer o cache e então reconecte.
Hosts totalmente offline — use o tarball do GitHub Release (Opção 2) e aponte o seu cliente para node /path/to/dist/index.js; nada é buscado em tempo de execução.

Claude Desktop — Configurações → Desenvolvedor → Servidores MCP → Editar Configuração e adicione o bloco JSON mostrado acima. Reinicie o aplicativo após editar; o servidor aparece na lista de ferramentas de uma nova conversa.

Claude Code (CLI) — registre o servidor por projeto ou globalmente:

claude mcp add elasticsearch \
  -e ES_URL=https://your-es:9200 -e ES_API_KEY=your-key \
  -- npx @tocharianou/elasticsearch-mcp

Qualquer outro cliente MCP / integração de plataforma — execute no modo HTTP (MCP_TRANSPORT=http, veja abaixo) e aponte o cliente para http://host:port/mcp; este é o formato recomendado para plataformas containerizadas, uma instância de servidor por conexão de cluster.

Higiene de credenciais — as variáveis de ambiente acabam no arquivo de configuração do seu cliente em texto simples. Prefira uma chave de API com escopo e somente leitura (veja Controle de Acesso ao Elasticsearch abaixo) em vez de credenciais de superusuário.

Método 3: Modo HTTP Streamable (NOVO na v0.3.0)

Execute o servidor como um serviço HTTP autônomo para acesso remoto e integração de API:

# Start HTTP server (default port 3000)
MCP_TRANSPORT=http \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

# Or with custom port and host
MCP_TRANSPORT=http \
MCP_HTTP_PORT=9000 \
MCP_HTTP_HOST=0.0.0.0 \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

Recursos do Modo HTTP Streamable:

Expõe o servidor MCP no endpoint http://host:port/mcp
Verificação de saúde disponível em http://host:port/health
Gerenciamento de conexão baseado em sessão
Suporta tanto POST (solicitações JSON-RPC) quanto GET (fluxos SSE)
Compatível com qualquer cliente HTTP ou SDK MCP

Qualquer cliente compatível com MCP (ou JSON-RPC simples sobre HTTP) pode falar com o endpoint /mcp: inicialize uma vez, mantenha o cabeçalho mcp-session-id retornado nas solicitações tools/list / tools/call subsequentes. Use /health para verificações de atividade.

Ferramentas Disponíveis

Ferramenta	Descrição	Versão Mínima
`list_indices`	Lista índices com filtro de padrão, filtro de saúde, ordenação e resumo ciente de tokens	ES 5.x+
`get_mappings`	Obtém mapeamentos de campos com modos plano/árvore/bruto, filtro de campos e comparação multi-índice	ES 5.x+
`es_search`	Pesquisa completa com Query DSL, realce automático, além de validação/correção automática de campos do harness	ES 5.x+
`lookup_fields`	Encontre os nomes de campos corretos: vocabulário ECS interseccionado com os campos reais do índice	ES 5.x+
`execute_es_api`	Execute qualquer endpoint REST do ES diretamente (GET/POST/PUT/DELETE/HEAD)	ES 5.x+
`get_shards`	Informações de shard com análise de saúde, detecção de problemas e recomendações	ES 5.x+
`list_data_streams`	Liste e analise Data Streams com informações de ILM e detalhes de índices de suporte	ES 7.9+
`esql_query`	Execute consultas baseadas em pipe do ES\|QL com validação de campos do harness e saída tabular	ES 8.11+

Ferramentas não suportadas pela versão do seu cluster são ignoradas automaticamente na inicialização. es_search e esql_query aceitam skip_lint: true para ignorar a validação do harness em casos extremos (ex.: campos de runtime definidos fora da consulta).

Ferramenta de Consulta ES|QL (`esql_query`)

ES|QL é a linguagem de consulta moderna baseada em pipe do Elasticsearch, ideal para análises e exploração de dados sem JSON DSL complexo.

Exemplos de consultas:

FROM logs-* | WHERE level == "error" | STATS count = COUNT(*) BY service | SORT count DESC | LIMIT 20
FROM metrics-* | WHERE @timestamp > NOW() - 1 hour | STATS avg_cpu = AVG(cpu.usage) BY host.name
FROM auditbeat-* | WHERE event.action == "user_login" AND event.outcome == "failure" | LIMIT 50

Parâmetros:

query — a string ES|QL (obrigatório)
params — parâmetros posicionais substituindo os placeholders ? (opcional)
include_types — incluir informações de tipo de coluna na saída (opcional, padrão false)
break_token_rule — ignorar o limite de tokens para resultados grandes (opcional, padrão false)
skip_lint — ignorar a validação de campos do harness (opcional, padrão false)

Registrado automaticamente apenas em clusters ES 8.11+.

Contribuindo

Aceitamos contribuições da comunidade! Para detalhes sobre como contribuir, consulte Diretrizes de Contribuição.

Como Funciona

O cliente MCP (o modelo de IA) decide o que procurar e chama uma ferramenta.
O harness valida a solicitação contra o cluster ativo — corrigindo o que é inequívoco, bloqueando o que falharia e traduzindo erros em orientações.
Os resultados retornam limitados por tokens e pré-processados (destaques, tabelas, resumos de agregações), para que investigações longas permaneçam dentro dos limites de contexto.

Exemplos de Análise de Segurança

[!TIP] Aqui estão consultas focadas em segurança que você pode experimentar com seu Cliente MCP.

Detecção de Ameaças:

"Analisar tentativas de ataque de força bruta nas últimas 24 horas"
"Detectar comportamento de login anormal e endereços IP suspeitos no sistema"
"Identificar padrões de ataque de injeção de SQL e solicitações maliciosas"
"Descobrir assinaturas de ataques DDoS e anomalias de tráfego em fluxos de rede"

Análise de Causa Raiz:

"Rastrear a cadeia completa de ataque e o escopo de impacto para incidentes de segurança específicos"
"Analisar causas raiz e caminhos de propagação de falhas do sistema"
"Identificar fontes de violação de dados e informações confidenciais envolvidas"
"Investigar incidentes de abuso de privilégios de usuário com linha do tempo e registros de operações"

Inteligência de Ameaças:

"Criar modelos de aprendizado de máquina para detectar ataques de dia zero e ameaças desconhecidas"
"Estabelecer linhas de base comportamentais e identificar atividades que se desviam dos padrões normais"
"Analisar níveis de ameaça e histórico de ataques de domínios e endereços IP maliciosos"
"Detectar características comportamentais e padrões de ataque de Ameaças Persistentes Avançadas (APT)"

Monitoramento em Tempo Real:

"Monitorar ameaças ativas e ataques em andamento no sistema atual"
"Detectar padrões anormais de acesso a dados e comportamentos de escalonamento de privilégios"
"Descobrir comunicações de rede suspeitas e atividades de exfiltração de dados"
"Identificar causas de segurança de consumo anormal de recursos do sistema e degradação de desempenho"

Melhores Práticas de Segurança

[!WARNING] Evite usar privilégios de administrador do cluster. Crie chaves de API dedicadas com escopo limitado e aplique controle de acesso refinado no nível do índice para evitar acesso não autorizado a dados.

Verificação de Integridade do Pacote

Ao baixar pacotes de lançamento, sempre verifique os checksums para garantir a integridade:

# Verify SHA256 checksum
shasum -a 256 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha256

# Verify SHA512 checksum
shasum -a 512 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha512

Isso protege contra:

Downloads corrompidos
Pacotes adulterados
Ataques man-in-the-middle

Controle de Acesso ao Elasticsearch

Você pode criar uma chave de API dedicada do Elasticsearch com permissões mínimas para controlar o acesso aos seus dados:

{
  "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"
          ]
        }
      ]
    }
  }
}

Licença

Este projeto é licenciado sob a Apache License 2.0.

Solução de Problemas

Certifique-se de que sua configuração MCP está correta.
Verifique se sua URL do Elasticsearch está acessível a partir da sua máquina.
Confirme que suas credenciais de autenticação (chave de API ou nome de usuário/senha) têm as permissões necessárias.
Se estiver usando SSL/TLS com uma CA personalizada, verifique se o caminho do certificado está correto e se o arquivo é legível.
Observe a saída do terminal para mensagens de erro.

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