Custom Elasticsearch

Um servidor MCP simples para Elasticsearch, projetado para ambientes em nuvem onde sua chave pública já está autorizada.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Custom Elasticsearch

Um servidor MCP (Model Context Protocol) simples para Elasticsearch, projetado para ambientes em nuvem onde sua chave pública já está autorizada no servidor.

Por que esta versão customizada?

Sem necessidade de API Key - Diferente do servidor MCP oficial do Elasticsearch, que requer tanto ES_URL quanto ES_API_KEY, esta versão só precisa da URL, pois sua chave pública já é confiável no servidor em nuvem.

Ferramentas aprimoradas - Melhor usabilidade com parâmetros opcionais e padrões melhorados em comparação com a versão oficial.

O que este servidor faz

Este servidor MCP conecta o Cursor ao seu cluster Elasticsearch com 4 ferramentas poderosas:

list_indices - Lista todos os índices (filtro de padrão opcional)
search - Suporte completo ao Elasticsearch Query DSL
get_mappings - Obtém mapeamentos de campos para qualquer índice
get_shards - Visualiza informações de shards do cluster

Início Rápido

Compilar a partir do código-fonte

git clone https://github.com/M0-AR/Custom-Elasticsearch-MCP-Server.git
cd Custom-Elasticsearch-MCP-Server
docker build -t elasticsearch-mcp:latest .

2. Adicionar à configuração MCP do Cursor

Adicione isto ao seu arquivo .cursor/mcp.json:

Configuração:

{
    "mcpServers": {
        "elasticsearch-custom": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--add-host=host.docker.internal:host-gateway",
                "-e",
                "ES_URL=http://host.docker.internal:9400",
                "elasticsearch-mcp:latest"
            ]
        }
    }
}

3. Reiniciar o Cursor

Feche e reabra o Cursor. Você deve ver o servidor elasticsearch-custom com 4 ferramentas habilitadas.

Configuração

Variáveis de ambiente:

ES_URL - Sua URL do Elasticsearch (padrão: http://localhost:9400)
MAX_CONNECTIONS - Máximo de conexões simultâneas (padrão: 100)
MAX_KEEPALIVE_CONNECTIONS - Máximo de conexões keepalive (padrão: 20)
CONNECTION_TIMEOUT - Timeout de conexão em segundos (padrão: 30)
REQUEST_TIMEOUT - Timeout de requisição em segundos (padrão: 30)

Para portas diferentes do Elasticsearch:

"ES_URL=http://host.docker.internal:9200"

Para ambientes de alto tráfego:

"MAX_CONNECTIONS=200",
"MAX_KEEPALIVE_CONNECTIONS=50",
"CONNECTION_TIMEOUT=60",
"REQUEST_TIMEOUT=60"

Exemplo de Uso

Uma vez conectado no Cursor, você pode:

Listar todos os índices: "Mostre-me todos os índices do elasticsearch"
Pesquisar dados: "Pesquise dados de vendas no índice hq.sales"
Obter mapeamentos: "Quais campos existem no índice hq.menuitems?"
Verificar cluster: "Mostre-me o status do cluster elasticsearch"

Comparação com o Servidor Oficial

Recurso	Servidor Oficial	Este Servidor Customizado
Autenticação	Requer `ES_URL` + `ES_API_KEY`	Apenas precisa de `ES_URL` (chave pública autorizada)
list_indices	Requer parâmetro `indexPattern`	Parâmetro opcional com padrão "*"
Ferramentas Disponíveis	4 ferramentas (mesmas funções)	4 ferramentas (usabilidade aprimorada)
Segurança	Baseada em API key	Autorização por chave pública
Concorrência	Bloqueio síncrono	Assíncrono com pool de conexões
Desempenho	Uma requisição por vez	100+ requisições simultâneas

Tratamento de Requisições Simultâneas

Este servidor MCP foi projetado para lidar com múltiplas requisições paralelas de vários aplicativos simultaneamente, usando as melhores práticas da indústria:

Recursos principais:

✅ Arquitetura Async/Await - I/O não bloqueante para processamento paralelo de requisições ✅ Pool de Conexões - Reutiliza conexões HTTP (até 100 simultâneas) ✅ Suporte HTTP/2 - Multiplexa múltiplas requisições em uma única conexão ✅ Limites Configuráveis - Ajuste os limites de conexão para sua carga de trabalho ✅ Thread-Safe - FastMCP lida com execução concorrente de ferramentas com segurança

Características de desempenho:

Padrão: 100 conexões simultâneas, 20 conexões keepalive
Escalável: Configure até 1000+ conexões simultâneas
Eficiente: Reutilização de conexões reduz a latência em ~50%
Confiável: Tratamento adequado de timeout previne esgotamento de conexões

Configuração para alto tráfego:

{
    "mcpServers": {
        "elasticsearch-custom": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--add-host=host.docker.internal:host-gateway",
                "-e", "ES_URL=http://host.docker.internal:9400",
                "-e", "MAX_CONNECTIONS=200",
                "-e", "MAX_KEEPALIVE_CONNECTIONS=50",
                "-e", "CONNECTION_TIMEOUT=60",
                "-e", "REQUEST_TIMEOUT=60",
                "elasticsearch-mcp:latest"
            ]
        }
    }
}

Testando requisições simultâneas:

# Test 10 parallel requests
for i in {1..10}; do
    echo '{"jsonrpc": "2.0", "id": '$i', "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}' | \
    python3 simple_elasticsearch_mcp.py &
done
wait

Arquivos

simple_elasticsearch_mcp.py - Servidor MCP principal
Dockerfile - Instruções de build do container
requirements.txt - Dependências Python

Testes Manuais

Testar o servidor diretamente:

python3 simple_elasticsearch_mcp.py

Testar com comandos JSON-RPC:

1. Listar todas as ferramentas:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | python3 simple_elasticsearch_mcp.py

2. Listar todos os índices:

echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}' | python3 simple_elasticsearch_mcp.py

3. Pesquisar dados:

echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search", "arguments": {"index": "hq.sales", "queryBody": {"query": {"match_all": {}}, "size": 3}}}}' | python3 simple_elasticsearch_mcp.py

4. Obter mapeamentos de índice:

echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "get_mappings", "arguments": {"index": "hq.menuitems"}}}' | python3 simple_elasticsearch_mcp.py

5. Verificar shards do cluster:

echo '{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "get_shards", "arguments": {}}}' | python3 simple_elasticsearch_mcp.py

Definir URL personalizada do Elasticsearch:

ES_URL="http://your-es-host:9200" python3 simple_elasticsearch_mcp.py

Solução de Problemas

❌ Erros de "Connection refused" ou "timed out"

Causa raiz: O problema mais comum é o networking do container Docker quando o Elasticsearch é acessível via túnel SSH.

Solução: Garanta que estes requisitos sejam atendidos:

1. O Túnel SSH Deve Estar Ativo

Se o seu Elasticsearch está atrás de túnel SSH (comum em implantações em nuvem):

# Start SSH tunnel to forward port 9400
ssh -L 9400:localhost:9400 -N -f -l username your-server-ip

# Verify tunnel is working
curl -X GET "localhost:9400/_cluster/health?pretty"

2. Configuração Docker Correta

Seu mcp.json deve usar exatamente esta configuração:

"elasticsearch-custom": {
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ES_URL=http://host.docker.internal:9400",
        "elasticsearch-mcp:latest"
    ]
}

Pontos-chave:

✅ Use --add-host=host.docker.internal:host-gateway (não endereços IP)
✅ Use ES_URL=http://host.docker.internal:9400 (não localhost)
✅ O túnel SSH deve estar em execução antes de iniciar o Cursor

3. Testar Conectividade Docker

# Test if Docker can reach your Elasticsearch
docker run --rm --add-host=host.docker.internal:host-gateway alpine/curl \
  curl -s http://host.docker.internal:9400/_cluster/health

4. Teste MCP Docker Completo

Teste o fluxo MCP completo com este comando abrangente:

# Full MCP server test with proper initialization
{
    echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}';
    echo '{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}';
    echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}';
} | docker run -i --rm --add-host=host.docker.internal:host-gateway -e ES_URL="http://host.docker.internal:9400" elasticsearch-mcp:latest

Saída esperada:

Resposta de inicialização com informações do servidor
Lista de todos os índices Elasticsearch em formato JSON
Nenhuma mensagem de erro

5. Alternativa: Modo Network Host

Se host-gateway não funcionar, tente o modo network host:

"args": [
    "run", "-i", "--rm", "--network=host",
    "-e", "ES_URL=http://localhost:9400",
    "elasticsearch-mcp:latest"
]

❌ "Received request before initialization was complete"

Causa raiz: O protocolo MCP requer sequência de inicialização adequada.

Solução: Sempre inicialize antes de chamar as ferramentas:

# Correct sequence:
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}'
echo '{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}'
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}'

É Isso!

Compilar → Adicionar à configuração → Reiniciar o Cursor → Pronto! 🚀