Octodet Elasticsearch MCP Server

Um servidor MCP para interagir com clusters Elasticsearch, permitindo que aplicações baseadas em LLM pesquisem, atualizem e gerenciem dados.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor MCP Octodet Elasticsearch

Um servidor Model Context Protocol (MCP) para operações com Elasticsearch, fornecendo um conjunto abrangente de ferramentas para interagir com clusters Elasticsearch através do Model Context Protocol padronizado. Este servidor permite que aplicações alimentadas por LLM pesquisem, atualizem e gerenciem dados do Elasticsearch.

octodet-elasticsearch-mcp MCP server

Recursos

  • Operações completas com Elasticsearch: Operações CRUD completas para documentos e índices
  • Operações em lote: Processe múltiplas operações em uma única chamada de API
  • Atualizações/Exclusões baseadas em consultas: Modifique ou remova documentos com base em consultas
  • Gerenciamento de cluster: Monitore saúde, shards e templates
  • Pesquisa avançada: Suporte completo para consultas DSL do Elasticsearch com destaque de resultados

Instalação

Como pacote NPM

Instale o pacote globalmente:

npm install -g @octodet/elasticsearch-mcp

Ou use diretamente com npx:

npx @octodet/elasticsearch-mcp

A partir do código-fonte

  1. Clone este repositório
  2. Instale as dependências:
npm install
  1. Compile o servidor:
npm run build

Integração com clientes MCP

Integração com VS Code

Adicione a seguinte configuração ao seu settings.json do VS Code para integrar com a extensão MCP do VS Code:

"mcp.servers": {
  "elasticsearch": {
    "command": "npx",
    "args": [
      "-y", "@octodet/elasticsearch-mcp"
    ],
    "env": {
      "ES_URL": "http://localhost:9200",
      "ES_API_KEY": "your_api_key",
      "ES_VERSION": "8"
    }
  }
}

Integração com Claude Desktop

Configure no seu arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "@octodet/elasticsearch-mcp"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

Para desenvolvimento local

Se você estiver desenvolvendo o servidor MCP localmente, pode configurar os clientes para usar sua compilação local:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

Configuração

O servidor utiliza as seguintes variáveis de ambiente para configuração:

VariávelDescriçãoPadrão
ES_URLURL do servidor Elasticsearchhttp://localhost:9200
ES_API_KEYChave de API para autenticação
ES_USERNAMENome de usuário para autenticação
ES_PASSWORDSenha para autenticação
ES_CA_CERTCaminho para certificado CA personalizado
ES_VERSIONVersão do Elasticsearch (8 ou 9)8
ES_SSL_SKIP_VERIFYIgnorar verificação SSLfalse
ES_PATH_PREFIXPrefixo de caminho para Elasticsearch

Ferramentas

O servidor fornece 16 ferramentas MCP para operações com Elasticsearch. Cada ferramenta é documentada com seus parâmetros obrigatórios e opcionais:

1. Listar Índices

Lista todos os índices Elasticsearch disponíveis com informações detalhadas.

Parâmetros:

  • indexPattern (opcional, string): Padrão para filtrar índices (ex.: "logs-", "my-index-")

Exemplo:

{
  "indexPattern": "logs-*"
}

2. Obter Mappings

Obtém os mappings de campos para um índice Elasticsearch específico.

Parâmetros:

  • index (obrigatório, string): O nome do índice para obter os mappings

Exemplo:

{
  "index": "my-index"
}

3. Pesquisar

Realiza uma pesquisa no Elasticsearch com o DSL de consulta fornecido e destaque de resultados.

Parâmetros:

  • index (obrigatório, string): O índice ou índices para pesquisar (suporta valores separados por vírgula)
  • queryBody (obrigatório, objeto): O corpo da consulta DSL do Elasticsearch
  • highlight (opcional, booleano): Ativar destaque de resultados da pesquisa (padrão: true)

Exemplo:

{
  "index": "my-index",
  "queryBody": {
    "query": {
      "match": {
        "content": "search term"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. Obter Saúde do Cluster

Obtém informações de saúde sobre o cluster Elasticsearch.

Parâmetros:

  • Nenhum obrigatório

Exemplo:

{}

5. Obter Shards

Obtém informações de shards para todos ou índices específicos.

Parâmetros:

  • index (opcional, string): Índice específico para obter informações de shards. Se omitido, retorna shards de todos os índices

Exemplo:

{
  "index": "my-index"
}

6. Adicionar Documento

Adiciona um novo documento a um índice Elasticsearch específico.

Parâmetros:

  • index (obrigatório, string): O índice para adicionar o documento
  • document (obrigatório, objeto): O conteúdo do documento a ser adicionado
  • id (opcional, string): ID do documento. Se omitido, o Elasticsearch gerará um automaticamente

Exemplo:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "My Document",
    "content": "Document content here",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["important", "draft"]
  }
}

7. Atualizar Documento

Atualiza um documento existente em um índice Elasticsearch específico.

Parâmetros:

  • index (obrigatório, string): O índice que contém o documento
  • id (obrigatório, string): O ID do documento a ser atualizado
  • document (obrigatório, objeto): O documento parcial com os campos a serem atualizados

Exemplo:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Updated Document Title",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. Excluir Documento

Exclui um documento de um índice Elasticsearch específico.

Parâmetros:

  • index (obrigatório, string): O índice que contém o documento
  • id (obrigatório, string): O ID do documento a ser excluído

Exemplo:

{
  "index": "my-index",
  "id": "doc1"
}

9. Atualizar por Consulta

Atualiza documentos em um índice Elasticsearch com base em uma consulta.

Parâmetros:

  • index (obrigatório, string): O índice para atualizar documentos
  • query (obrigatório, objeto): Consulta Elasticsearch para corresponder documentos para atualização
  • script (obrigatório, objeto): Script a ser executado para atualizar os documentos correspondentes
  • conflicts (opcional, string): Como lidar com conflitos de versão ("abort" ou "proceed", padrão: "abort")
  • refresh (opcional, booleano): Se deve atualizar o índice após a operação (padrão: false)

Exemplo:

{
  "index": "my-index",
  "query": {
    "term": {
      "status": "active"
    }
  },
  "script": {
    "source": "ctx._source.status = params.newStatus; ctx._source.updated_at = params.timestamp",
    "params": {
      "newStatus": "inactive",
      "timestamp": "2025-06-23T10:30:00Z"
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

10. Excluir por Consulta

Exclui documentos em um índice Elasticsearch com base em uma consulta.

Parâmetros:

  • index (obrigatório, string): O índice para excluir documentos
  • query (obrigatório, objeto): Consulta Elasticsearch para corresponder documentos para exclusão
  • conflicts (opcional, string): Como lidar com conflitos de versão ("abort" ou "proceed", padrão: "abort")
  • refresh (opcional, booleano): Se deve atualizar o índice após a operação (padrão: false)

Exemplo:

{
  "index": "my-index",
  "query": {
    "range": {
      "created_date": {
        "lt": "2025-01-01"
      }
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

11. Operações em Lote

Realiza múltiplas operações de documentos em uma única chamada de API para melhor desempenho.

Parâmetros:

  • operations (obrigatório, array): Matriz de objetos de operação, cada um contendo:
    • action (obrigatório, string): O tipo de operação ("index", "create", "update" ou "delete")
    • index (obrigatório, string): O índice para esta operação
    • id (opcional, string): ID do documento (obrigatório para update/delete, opcional para index/create)
    • document (condicional, objeto): Conteúdo do documento (obrigatório para operações index/create/update)

Exemplo:

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Document 1", "content": "Content here" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Updated Title" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. Criar Índice

Cria um novo índice Elasticsearch com configurações e mappings opcionais.

Parâmetros:

  • index (obrigatório, string): O nome do índice a ser criado
  • settings (opcional, objeto): Configurações do índice como número de shards, réplicas, etc.
  • mappings (opcional, objeto): Mappings de campos definindo como os documentos devem ser indexados

Exemplo:

{
  "index": "new-index",
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "analysis": {
      "analyzer": {
        "custom_analyzer": {
          "type": "standard",
          "stopwords": "_english_"
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "custom_analyzer"
      },
      "created": {
        "type": "date",
        "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
      },
      "tags": {
        "type": "keyword"
      }
    }
  }
}

13. Excluir Índice

Exclui permanentemente um índice Elasticsearch.

Parâmetros:

  • index (obrigatório, string): O nome do índice a ser excluído

Exemplo:

{
  "index": "my-index"
}

14. Contar Documentos

Conta documentos em um índice, opcionalmente filtrados por uma consulta.

Parâmetros:

  • index (obrigatório, string): O índice para contar documentos
  • query (opcional, objeto): Consulta Elasticsearch para filtrar documentos para contagem

Exemplo:

{
  "index": "my-index",
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "active" } },
        { "range": { "created_date": { "gte": "2025-01-01" } } }
      ]
    }
  }
}

15. Obter Templates

Obtém templates de índice do Elasticsearch.

Parâmetros:

  • name (opcional, string): Nome específico do template a ser recuperado. Se omitido, retorna todos os templates

Exemplo:

{
  "name": "logs-template"
}

16. Obter Aliases

Obtém aliases de índice do Elasticsearch.

Parâmetros:

  • name (opcional, string): Nome específico do alias a ser recuperado. Se omitido, retorna todos os aliases

Exemplo:

{
  "name": "logs-alias"
}

Desenvolvimento

Executando em modo de desenvolvimento

Execute o servidor em modo de observação durante o desenvolvimento:

npm run dev

Implementação do protocolo

Este servidor implementa o Model Context Protocol para permitir comunicação padronizada entre clientes LLM e Elasticsearch. Ele fornece um conjunto de ferramentas que podem ser invocadas por clientes MCP para realizar várias operações no Elasticsearch.

Adicionando novas ferramentas

Para adicionar uma nova ferramenta ao servidor:

  1. Defina a ferramenta em src/index.ts usando o formato de registro de ferramentas do servidor MCP
  2. Implemente a funcionalidade necessária em src/utils/elasticsearchService.ts
  3. Atualize este README para documentar a nova ferramenta

Outros clientes MCP

Este servidor pode ser usado com qualquer cliente compatível com MCP, incluindo:

  • ChatGPT da OpenAI via plugins MCP
  • Claude Desktop da Anthropic
  • Claude no VS Code
  • Aplicações personalizadas usando o SDK MCP

Uso programático

Você também pode usar o servidor programaticamente em suas aplicações Node.js:

import { createOctodetElasticsearchMcpServer } from "@octodet/elasticsearch-mcp";
import { CustomTransport } from "@modelcontextprotocol/sdk/server";

// Configure the Elasticsearch connection
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Create and start the server
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Connect to your custom transport
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Elasticsearch MCP server started");
}

startServer().catch(console.error);

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.