Elasticsearch/OpenSearch MCP Sunucusu

Genel Bakış

Elasticsearch ve OpenSearch ile etkileşim sağlayan bir Model Context Protocol (MCP) sunucu implementasyonu. Bu sunucu, bir dizi araç aracılığıyla belgeleri arama, indexleri analiz etme ve kümeri yönetme işlemlerini sağlar.

Demo

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

Özellikler

Genel İşlemler

• general_api_request: Genel HTTP API isteği gerçekleştirin. Dedicated bir aracı olmayan herhangi bir Elasticsearch/OpenSearch API'si için bu aracı kullanın.

Index İşlemleri

• list_indices: Tüm indexleri listeleyin.
• get_index: Bir veya daha fazla index hakkında bilgi döndürür (mappings, settings, aliases).
• create_index: Yeni bir index oluşturun.
• delete_index: Bir index silin.
• create_data_stream: Yeni bir data stream oluşturun (eşleşen index template gerektirir).
• get_data_stream: Bir veya daha fazla data stream hakkında bilgi alın.
• delete_data_stream: Bir veya daha fazla data stream ve bunların backing indexlerini silin.

Doküman İşlemleri

• search_documents: Belgeleri arayın.
• index_document: Index'te bir dokümanı oluşturun veya güncelleyin.
• get_document: ID'ye göre bir doküman alın.
• delete_document: ID'ye göre bir dokümanı silin.
• delete_by_query: Sağlanan sorguya eşleşen dokümanları silin.

Küme İşlemleri

• get_cluster_health: Kümenin sağlığı hakkında temel bilgiler döndürür.
• get_cluster_stats: Küme istatistiklerinin yüksek düzey genel görünümünü döndürür.

Alias İşlemleri

• list_aliases: Tüm aliasları listeleyin.
• get_alias: Belirli bir index için alias bilgisini alın.
• put_alias: Belirli bir index için bir alias oluşturun veya güncelleyin.
• delete_alias: Belirli bir index için bir alias silin.

Analyzer İşlemleri

• analyze_text: Belirtilen bir analyzer veya custom analysis chain kullanarak metni analiz edin. Arama sorgularında hata ayıklama ve metnin nasıl tokenize edildiğini anlamak için faydalıdır.

Ortam Değişkenlerini Yapılandırın

MCP sunucusu aşağıdaki ortam değişkenlerini destekler:

Temel Kimlik Doğrulama (Kullanıcı Adı/Şifre)

• ELASTICSEARCH_USERNAME: Temel kimlik doğrulama için kullanıcı adı
• ELASTICSEARCH_PASSWORD: Temel kimlik doğrulama için şifre
• OPENSEARCH_USERNAME: OpenSearch temel kimlik doğrulaması için kullanıcı adı
• OPENSEARCH_PASSWORD: OpenSearch temel kimlik doğrulaması için şifre

API Anahtarı Kimlik Doğrulaması (Yalnızca Elasticsearch) - Önerilen

• ELASTICSEARCH_API_KEY: Elasticsearch veya Elastic Cloud Kimlik Doğrulaması için API anahtarı.

Bağlantı Ayarları

• ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: Virgülle ayrılmış host listesi (varsayılan: https://localhost:9200)
• ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS: Named cluster konfigürasyonları için inline JSON nesnesi. Ayarlandığında, araçlar isteğe bağlı cluster parametresiyle belirli bir kümeler hedefleyebilir.
• ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE: clusters nesnesi ile bir JSON dosyasına giden yol. Konfigürasyon başka bir JSON dosyasının içine gömüldüğünde (örn. MCP istemci config) önerilir çünkü JSON-in-JSON kaçışından kaçınır. Her iki set olduğunda inline değişkenden önceliklidir.
• DEFAULT_CLUSTER: Multi-cluster konfigürasyonu ayarlandığında ve bir araç çağrısı cluster parametresini atladığında kullanılacak varsayılan küme adı (varsayılan olarak yapılandırılan ilk küme).
• VERIFY_CERTS: SSL sertifikalarını doğrulayıp doğrulamayacağını belirtir (varsayılan: false)
• REQUEST_TIMEOUT: Request timeout süresi (saniye cinsinden) (isteğe bağlı, ayarlanmadıysa istemci varsayılanını kullanır)

Çoklu Küme Konfigürasyonu

Varsayılan olarak, sunucu ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD ve ELASTICSEARCH_API_KEY'den tek bir Elasticsearch kümesini, veya OPENSEARCH_HOSTS, OPENSEARCH_USERNAME ve OPENSEARCH_PASSWORD'den tek bir OpenSearch kümesini kullanır. Çoklu named kümeler yapılandırmak için ELASTICSEARCH_CLUSTERS (veya OPENSEARCH_CLUSTERS) değişkenini MCP sunucu konfigürasyonu içinde bir JSON nesnesi olarak ayarlayın. Değer başka bir JSON dosyasına gömülü bir JSON dizesi olduğundan, iç tırnak işaretlerinin kaçırılması gerekir:

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

Daha iyi okunabilirlik için, ELASTICSEARCH_CLUSTERS_FILE (veya OPENSEARCH_CLUSTERS_FILE) değişkenini bunun yerine bağımsız bir JSON dosyasına işaret ettirin. Değer sadece bir yol olduğundan JSON-in-JSON kaçışından kaçınır:

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

Her araç isteğe bağlı bir cluster parametresini kabul eder. Atlanırsa, sunucu DEFAULT_CLUSTER değerini kullanır. DEFAULT_CLUSTER ayarlanmadığında, JSON nesnesindeki ilk küme varsayılan olarak kullanılır. Belirli bir kümeler hedef alan bir araç çağrısı şuna benzer:

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

MCP Sunucusu Kimlik Doğrulaması (Yalnızca HTTP Transports)

MCP sunucusunu HTTP tabanlı transportlarla (SSE veya Streamable HTTP) çalıştırırken, sunucuyu yetkisiz erişimden korumak için Bearer token kimlik doğrulamasını etkinleştirebilirsiniz.

• MCP_API_KEY: MCP sunucusu kimlik doğrulaması için API anahtarı. İstemciler Authorization: Bearer <MCP_API_KEY> header'ını içermelidir.

Önemli Güvenlik Notları:

• Kimlik doğrulama yalnızca HTTP transportları (sse, streamable-http) için geçerlidir. stdio transport yerel process iletişimi kullanır ve kimlik doğrulama gerektirmez.
• MCP_API_KEY ayarlanmadıysa, MCP sunucusu kimlik doğrulama olmadan erişilebilir olacaktır. Bu, sunucuyu ağ üzerinden gösterirken bir güvenlik riski oluşturur.
• HTTP transportları ile production dağıtımları için her zaman MCP_API_KEY ayarlayın.

# Güvenli bir API anahtarı oluşturun (openssl kullanarak örnek)
export MCP_API_KEY=$(openssl rand -base64 32)

# Veya custom bir API anahtarı ayarlayın
export MCP_API_KEY="your-secure-api-key-here"

Yüksek Riskli İşlemleri Devre Dışı Bırakın

• DISABLE_HIGH_RISK_OPERATIONS: Tüm write işlemlerini devre dışı bırakmak için true olarak ayarlayın (varsayılan: false)
• DISABLE_OPERATIONS: Devre dışı bırakılacak belirli işlemlerin virgülle ayrılmış listesi (isteğe bağlı, ayarlanmadıysa varsayılan write işlemleri listesini kullanır)

DISABLE_HIGH_RISK_OPERATIONS true olarak ayarlandığında, write işlemleri gerçekleştiren tüm MCP araçları MCP istemcisinden tamamen gizlenir. Bu modda, aşağıdaki MCP araçları varsayılan olarak devre dışı bırakılır.

• Index İşlemleri:

  • create_index
  • delete_index

• Doküman İşlemleri:

  • index_document
  • delete_document
  • delete_by_query

• Data Stream İşlemleri:

  • create_data_stream
  • delete_data_stream

• Alias İşlemleri:

  • put_alias
  • delete_alias

• Genel API İşlemleri:

  • general_api_request

İsteğe bağlı olarak, DISABLE_OPERATIONS ortam değişkeninde devre dışı bırakılacak işlemlerin virgülle ayrılmış listesini belirtebilirsiniz.

# Yüksek Riskli İşlemleri Devre Dışı Bırakın
export DISABLE_HIGH_RISK_OPERATIONS=true
# Yalnızca belirli işlemleri devre dışı bırakın
export DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"

Elasticsearch/OpenSearch Kümesini Başlatın

Docker Compose kullanarak Elasticsearch/OpenSearch kümesini başlatın:

# Elasticsearch için
docker-compose -f docker-compose-elasticsearch.yml up -d

# OpenSearch için
docker-compose -f docker-compose-opensearch.yml up -d

Varsayılan Elasticsearch kullanıcı adı elastic ve şifre test123'dir. Varsayılan OpenSearch kullanıcı adı admin ve şifre admin'dir.

Kibana/OpenSearch Dashboards'a http://localhost:5601'den erişebilirsiniz.

Stdio

Seçenek 1: uvx Kullanma

uvx kullanmak paketi PyPI'den otomatik olarak yükleyecektir, yerel olarak depoyu klonlamaya gerek yoktur. Aşağıdaki konfigürasyonu claude_desktop_config.json config dosyasına ekleyin.

// Elasticsearch kullanıcı adı/şifre ile
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// Elasticsearch API anahtarı ile
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
      }
    }
  }
}

// OpenSearch için
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": [
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

Seçenek 2: Yerel geliştirme ile uv Kullanma

uv kullanmak depoyu yerel olarak klonlamayı ve kaynak koda giden yolu belirtmeyi gerektirir. Aşağıdaki konfigürasyonu Claude Desktop'ın config dosyası claude_desktop_config.json'a ekleyin.

// Elasticsearch kullanıcı adı/şifre ile
{
  "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"
      }
    }
  }
}

// Elasticsearch API anahtarı ile
{
  "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>"
      }
    }
  }
}

// OpenSearch için
{
  "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

Seçenek 1: uvx Kullanma

# Ortam değişkenlerini dışa aktarın (kullanıcı adı/şifre ile)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# VEYA ortam değişkenlerini dışa aktarın (API anahtarı ile)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# Varsayılan olarak, SSE MCP sunucusu http://127.0.0.1:8000/sse üzerinde hizmet verecektir
uvx elasticsearch-mcp-server --transport sse

# Host, port ve path değerleri --host, --port ve --path seçenekleri kullanılarak belirtilebilir
uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Seçenek 2: uv Kullanma

# Varsayılan olarak, SSE MCP sunucusu http://127.0.0.1:8000/sse üzerinde hizmet verecektir
uv run src/server.py elasticsearch-mcp-server --transport sse

# Host, port ve path değerleri --host, --port ve --path seçenekleri kullanılarak belirtilebilir
uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Streamable HTTP

Seçenek 1: uvx Kullanma

# Ortam değişkenlerini dışa aktarın (kullanıcı adı/şifre ile)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# VEYA ortam değişkenlerini dışa aktarın (API anahtarı ile)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# Varsayılan olarak, Streamable HTTP MCP sunucusu http://127.0.0.1:8000/mcp üzerinde hizmet verecektir
uvx elasticsearch-mcp-server --transport streamable-http

# Host, port ve path değerleri --host, --port ve --path seçenekleri kullanılarak belirtilebilir
uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Seçenek 2: uv Kullanma

# Varsayılan olarak, Streamable HTTP MCP sunucusu http://127.0.0.1:8000/mcp üzerinde hizmet verecektir
uv run src/server.py elasticsearch-mcp-server --transport streamable-http

# Host, port ve path değerleri --host, --port ve --path seçenekleri kullanılarak belirtilebilir
uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Uyumluluk

MCP sunucusu Elasticsearch 7.x, 8.x ve 9.x ile uyumludur. Varsayılan olarak, Elasticsearch 8.x istemcisini (suffix olmadan) kullanır.

MCP Sunucusu	Elasticsearch
elasticsearch-mcp-server-es7	Elasticsearch 7.x
elasticsearch-mcp-server	Elasticsearch 8.x
elasticsearch-mcp-server-es9	Elasticsearch 9.x
opensearch-mcp-server	OpenSearch 1.x, 2.x, 3.x

Elasticsearch 7.x istemcisini kullanmak için elasticsearch-mcp-server-es7 varyantını çalıştırın. Elasticsearch 9.x için elasticsearch-mcp-server-es9 varyantını kullanın. Örneğin:

uvx elasticsearch-mcp-server-es7

Farklı Elasticsearch varyantlarını (örn. 7.x veya 9.x) yerel olarak çalıştırmak istiyorsanız, pyproject.toml'deki elasticsearch dependency sürümünü güncellemeniz yeterlidir, ardından sunucuyu şu şekilde başlatın:

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

Kubernetes Dağıtımı

Docker imajı ghcr.io/cr7258/elasticsearch-mcp-server adresine yayımlanmıştır ve Helm chart'ı oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server repository'sinde bir OCI artifact olarak kullanılabilir.

Tam kurulum talimatları, konfigürasyon referansı ve kullanım örnekleri için Helm chart README başvurunuz.

Lisans

Bu proje Apache License Version 2.0 altında lisanslanmıştır - ayrıntılar için LICENSE dosyasına bakınız.