Elasticsearch/OpenSearch

Um servidor MCP para interagir com clusters Elasticsearch e OpenSearch.

GitHub
308
Experimente este MCPPatrocinado

Documentação

Elasticsearch/OpenSearch MCP Server

MseeP.ai Security Assessment Badge

Trust Score

Visão Geral

Uma implementação de servidor Model Context Protocol (MCP) que fornece interação com Elasticsearch e OpenSearch. Este servidor permite pesquisar documentos, analisar índices e gerenciar o cluster por meio de um conjunto de ferramentas.

Elasticsearch MCP Server

Demo

https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15

Recursos

Operações Gerais

  • general_api_request: Executa uma requisição HTTP genérica à API. Use esta ferramenta para qualquer API do Elasticsearch/OpenSearch que não possua uma ferramenta dedicada.

Operações de Índice

  • list_indices: Lista todos os índices.
  • get_index: Retorna informações (mapeamentos, configurações, aliases) sobre um ou mais índices.
  • create_index: Cria um novo índice.
  • delete_index: Exclui um índice.
  • create_data_stream: Cria um novo data stream (requer um index template correspondente).
  • get_data_stream: Obtém informações sobre um ou mais data streams.
  • delete_data_stream: Exclui um ou mais data streams e seus índices de suporte.

Operações de Documento

  • search_documents: Pesquisa documentos.
  • index_document: Cria ou atualiza um documento no índice.
  • get_document: Obtém um documento por ID.
  • delete_document: Exclui um documento por ID.
  • delete_by_query: Exclui documentos que correspondem à consulta fornecida.

Operações de Cluster

  • get_cluster_health: Retorna informações básicas sobre a saúde do cluster.
  • get_cluster_stats: Retorna uma visão geral das estatísticas do cluster.

Operações de Alias

  • list_aliases: Lista todos os aliases.
  • get_alias: Obtém informações de alias para um índice específico.
  • put_alias: Cria ou atualiza um alias para um índice específico.
  • delete_alias: Exclui um alias para um índice específico.

Operações de Analisador

  • analyze_text: Analisa texto usando um analisador especificado ou cadeia de análise personalizada. Útil para depurar consultas de pesquisa e entender como o texto é tokenizado.

Configurar Variáveis de Ambiente

O servidor MCP suporta as seguintes variáveis de ambiente:

Autenticação Básica (Usuário/Senha)

  • ELASTICSEARCH_USERNAME: Nome de usuário para autenticação básica
  • ELASTICSEARCH_PASSWORD: Senha para autenticação básica
  • OPENSEARCH_USERNAME: Nome de usuário para autenticação básica do OpenSearch
  • OPENSEARCH_PASSWORD: Senha para autenticação básica do OpenSearch

Autenticação por Chave de API (somente Elasticsearch) - Recomendado

Configurações de Conexão

  • ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: Lista de hosts separados por vírgula (padrão: https://localhost:9200)
  • ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS: Objeto JSON inline para configurações de clusters nomeados. Quando definido, as ferramentas podem direcionar um cluster específico com o parâmetro opcional cluster.
  • ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE: Caminho para um arquivo JSON com o objeto de clusters. Recomendado quando a configuração está embutida em outro arquivo JSON (ex.: configuração do cliente MCP), pois evita o escape JSON-dentro-de-JSON. Tem precedência sobre a variável inline quando ambas estão definidas.
  • DEFAULT_CLUSTER: Nome padrão do cluster a ser usado quando a configuração de múltiplos clusters está definida e uma chamada de ferramenta omite cluster (o padrão é o primeiro cluster configurado).
  • VERIFY_CERTS: Se deve verificar certificados SSL (padrão: false)
  • REQUEST_TIMEOUT: Tempo limite de requisição em segundos (opcional, usa o padrão do cliente se não definido)

Configuração de Múltiplos Clusters

Por padrão, o servidor usa um único cluster Elasticsearch a partir de ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD e ELASTICSEARCH_API_KEY, ou um único cluster OpenSearch a partir de OPENSEARCH_HOSTS, OPENSEARCH_USERNAME e OPENSEARCH_PASSWORD. Para configurar múltiplos clusters nomeados, defina ELASTICSEARCH_CLUSTERS (ou OPENSEARCH_CLUSTERS) como um objeto JSON dentro da configuração do servidor MCP. Como o valor é uma string JSON embutida em outro arquivo JSON, as aspas internas precisam ser escapadas:

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

Para melhor legibilidade, aponte ELASTICSEARCH_CLUSTERS_FILE (ou OPENSEARCH_CLUSTERS_FILE) para um arquivo JSON independente. O valor é apenas um caminho, evitando o escape JSON-dentro-de-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>"
  }
}

Cada ferramenta aceita um parâmetro opcional cluster. Se omitido, o servidor usa DEFAULT_CLUSTER. Quando DEFAULT_CLUSTER não está definido, o primeiro cluster no objeto JSON é usado como padrão. Uma chamada de ferramenta direcionada a um cluster específico tem a seguinte aparência:

{
  "cluster": "staging",
  "index": "logs-*",
  "body": {
    "query": {
      "match_all": {}
    }
  }
}

Autenticação do Servidor MCP (Somente Transportes HTTP)

Ao executar o servidor MCP com transportes baseados em HTTP (SSE ou Streamable HTTP), você pode habilitar a autenticação por token Bearer para proteger o servidor contra acesso não autorizado.

  • MCP_API_KEY: Chave de API para autenticação do servidor MCP. Os clientes devem incluir o cabeçalho Authorization: Bearer <MCP_API_KEY>.

Notas de Segurança Importantes:

  • A autenticação é aplicável apenas para transportes HTTP (sse, streamable-http). O transporte stdio usa comunicação local entre processos e não requer autenticação.
  • Se MCP_API_KEY não estiver definido, o servidor MCP ficará acessível sem autenticação. Isso é um risco de segurança ao expor o servidor em uma rede.
  • Para implantações em produção com transportes HTTP, sempre defina 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"

Desabilitar Operações de Alto Risco

  • DISABLE_HIGH_RISK_OPERATIONS: Defina como true para desabilitar todas as operações de escrita (padrão: false)
  • DISABLE_OPERATIONS: Lista de operações específicas para desabilitar, separadas por vírgula (opcional, usa a lista padrão de operações de escrita se não definido)

Quando DISABLE_HIGH_RISK_OPERATIONS está definido como true, todas as ferramentas MCP que realizam operações de escrita ficam completamente ocultas do cliente MCP. Nesse modo, as seguintes ferramentas MCP são desabilitadas por padrão.

  • Operações de Índice:

    • create_index
    • delete_index

  • Operações de Documento:

    • index_document
    • delete_document
    • delete_by_query

  • Operações de Data Stream:

    • create_data_stream
    • delete_data_stream

  • Operações de Alias:

    • put_alias
    • delete_alias

  • Operações Gerais de API:

    • general_api_request

Opcionalmente, você pode especificar uma lista de operações para desabilitar, separadas por vírgula, na variável de ambiente 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"

Codificação de Resposta GCF (opcional)

Opte por serializar os payloads de resultados das ferramentas como GCF (Graph Compact Format), um formato de transmissão otimizado para tokens, no bloco de conteúdo que o modelo lê. O Elasticsearch retorna grandes conjuntos de registros uniformes (resultados de pesquisa, buckets de agregação, mapeamentos), o formato que o GCF compacta melhor: em respostas representativas, são ~39% menos tokens que JSON compacto (40% em resultados de pesquisa), sem perdas.

export RESPONSE_FORMAT=gcf

structuredContent é preservado inalterado, portanto o esquema de saída declarado de uma ferramenta continua válido e qualquer cliente não-modelo continua recebendo JSON; apenas o bloco de texto voltado ao modelo é recodificado. A codificação é à prova de falhas: qualquer erro, incluindo um valor fora do domínio numérico canônico int64 do GCF (que o GCF rejeita em vez de aproximar silenciosamente), deixa o resultado JSON original intacto, portanto uma chamada de ferramenta nunca é descartada por causa da codificação. O comportamento padrão permanece inalterado quando RESPONSE_FORMAT não está definido.

Reproduza a comparação de tokens: uv run --with tiktoken python benchmarks/gcf_benchmark.py.

Iniciar Cluster Elasticsearch/OpenSearch

Inicie o cluster Elasticsearch/OpenSearch usando Docker Compose:

# For Elasticsearch
docker-compose -f docker-compose-elasticsearch.yml up -d

# For OpenSearch
docker-compose -f docker-compose-opensearch.yml up -d

O nome de usuário padrão do Elasticsearch é elastic e a senha é test123. O nome de usuário padrão do OpenSearch é admin e a senha é admin.

Você pode acessar o Kibana/OpenSearch Dashboards em http://localhost:5601.

Stdio

Opção 1: Usando uvx

Usar uvx instalará automaticamente o pacote do PyPI, sem necessidade de clonar o repositório localmente. Adicione a seguinte configuração ao arquivo de configuração 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"
      }
    }
  }
}

Opção 2: Usando uv com desenvolvimento local

Usar uv requer clonar o repositório localmente e especificar o caminho para o código-fonte. Adicione a seguinte configuração ao arquivo de configuração do 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

Opção 1: Usando 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

Opção 2: Usando 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 /sse

Streamable HTTP

Opção 1: Usando 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

Opção 2: Usando 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

Compatibilidade

O servidor MCP é compatível com Elasticsearch 7.x, 8.x e 9.x. Por padrão, ele usa o cliente Elasticsearch 8.x (sem sufixo).

MCP ServerElasticsearch
elasticsearch-mcp-server-es7Elasticsearch 7.x
elasticsearch-mcp-serverElasticsearch 8.x
elasticsearch-mcp-server-es9Elasticsearch 9.x
opensearch-mcp-serverOpenSearch 1.x, 2.x, 3.x

Para usar o cliente Elasticsearch 7.x, execute a variante elasticsearch-mcp-server-es7. Para Elasticsearch 9.x, use elasticsearch-mcp-server-es9. Por exemplo:

uvx elasticsearch-mcp-server-es7

Se você quiser executar diferentes variantes do Elasticsearch (ex.: 7.x ou 9.x) localmente, basta atualizar a versão da dependência elasticsearch em pyproject.toml e iniciar o servidor com:

uv run src/server.py elasticsearch-mcp-server

Implantação no Kubernetes

A imagem Docker é publicada em ghcr.io/cr7258/elasticsearch-mcp-server e o Helm chart está disponível como um artefato OCI no repositório oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server.

Para instruções completas de instalação, referência de configuração e exemplos de uso, consulte o README do Helm chart.

Licença

Este projeto é licenciado sob a Apache License Versão 2.0 - consulte o arquivo LICENSE para obter detalhes.