Elasticsearch MCP Server
Elasticsearch/OpenSearch MCP Server
개요
Elasticsearch 및 OpenSearch와 상호작용을 제공하는 Model Context Protocol (MCP) 서버 구현입니다. 이 서버는 일련의 도구를 통해 문서 검색, 인덱스 분석, 클러스터 관리를 지원합니다.
Related MCP server: Elasticsearch MCP Server
데모
https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15
기능
일반 작업
general_api_request: 일반 HTTP API 요청을 수행합니다. 전용 도구가 없는 Elasticsearch/OpenSearch API에 대해 이 도구를 사용하세요.
인덱스 작업
list_indices: 모든 인덱스를 나열합니다.get_index: 하나 이상의 인덱스에 대한 정보(매핑, 설정, 별칭)를 반환합니다.create_index: 새 인덱스를 생성합니다.delete_index: 인덱스를 삭제합니다.create_data_stream: 새 데이터 스트림을 생성합니다(일치하는 인덱스 템플릿 필요).get_data_stream: 하나 이상의 데이터 스트림에 대한 정보를 가져옵니다.delete_data_stream: 하나 이상의 데이터 스트림과 해당 백킹 인덱스를 삭제합니다.
문서 작업
search_documents: 문서를 검색합니다.index_document: 인덱스에 문서를 생성하거나 업데이트합니다.get_document: ID로 문서를 가져옵니다.delete_document: ID로 문서를 삭제합니다.delete_by_query: 제공된 쿼리와 일치하는 문서를 삭제합니다.
클러스터 작업
get_cluster_health: 클러스터 상태에 대한 기본 정보를 반환합니다.get_cluster_stats: 클러스터 통계에 대한 높은 수준의 개요를 반환합니다.
별칭 작업
list_aliases: 모든 별칭을 나열합니다.get_alias: 특정 인덱스에 대한 별칭 정보를 가져옵니다.put_alias: 특정 인덱스에 대한 별칭을 생성하거나 업데이트합니다.delete_alias: 특정 인덱스에 대한 별칭을 삭제합니다.
분석기 작업
analyze_text: 지정된 분석기 또는 사용자 정의 분석 체인을 사용하여 텍스트를 분석합니다. 검색 쿼리 디버깅과 텍스트가 토큰화되는 방식을 이해하는 데 유용합니다.
환경 변수 구성
MCP 서버는 다음 환경 변수를 지원합니다:
기본 인증 (사용자 이름/비밀번호)
ELASTICSEARCH_USERNAME: 기본 인증을 위한 사용자 이름ELASTICSEARCH_PASSWORD: 기본 인증을 위한 비밀번호OPENSEARCH_USERNAME: OpenSearch 기본 인증을 위한 사용자 이름OPENSEARCH_PASSWORD: OpenSearch 기본 인증을 위한 비밀번호
API 키 인증 (Elasticsearch 전용) - 권장
ELASTICSEARCH_API_KEY: Elasticsearch 또는 Elastic Cloud 인증을 위한 API 키입니다.
연결 설정
ELASTICSEARCH_HOSTS/OPENSEARCH_HOSTS: 쉼표로 구분된 호스트 목록 (기본값:https://localhost:9200)ELASTICSEARCH_CLUSTERS/OPENSEARCH_CLUSTERS: 명명된 클러스터 구성을 위한 인라인 JSON 객체입니다. 설정 시 도구는 선택적cluster매개변수로 특정 클러스터를 대상으로 지정할 수 있습니다.ELASTICSEARCH_CLUSTERS_FILE/OPENSEARCH_CLUSTERS_FILE: 클러스터 객체가 포함된 JSON 파일의 경로입니다. 구성이 다른 JSON 파일(예: MCP 클라이언트 구성)에 포함된 경우 JSON-in-JSON 이스케이프를 피할 수 있으므로 권장됩니다. 두 변수가 모두 설정된 경우 인라인 변수보다 우선합니다.DEFAULT_CLUSTER: 다중 클러스터 구성이 설정되고 도구 호출에서cluster를 생략할 때 사용할 기본 클러스터 이름입니다(기본값은 첫 번째 구성된 클러스터).VERIFY_CERTS: SSL 인증서를 검증할지 여부 (기본값:false)REQUEST_TIMEOUT: 요청 제한 시간(초) (선택 사항, 설정하지 않으면 클라이언트 기본값 사용)
다중 클러스터 구성
기본적으로 서버는 ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD, ELASTICSEARCH_API_KEY의 단일 Elasticsearch 클러스터 또는 OPENSEARCH_HOSTS, OPENSEARCH_USERNAME, OPENSEARCH_PASSWORD의 단일 OpenSearch 클러스터를 사용합니다. 여러 명명된 클러스터를 구성하려면 MCP 서버 구성 내부의 JSON 객체로 ELASTICSEARCH_CLUSTERS(또는 OPENSEARCH_CLUSTERS)를 설정하세요. 값이 다른 JSON 파일에 포함된 JSON 문자열이므로 내부 따옴표를 이스케이프해야 합니다:
{
"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"
}
}
}
}가독성을 높이려면 대신 ELASTICSEARCH_CLUSTERS_FILE(또는 OPENSEARCH_CLUSTERS_FILE)을 독립형 JSON 파일로 지정하세요. 값은 단순한 경로이므로 JSON-in-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>"
}
}모든 도구는 선택적 cluster 매개변수를 허용합니다. 생략하면 서버는 DEFAULT_CLUSTER를 사용합니다. DEFAULT_CLUSTER가 설정되지 않은 경우 JSON 객체의 첫 번째 클러스터가 기본값으로 사용됩니다. 특정 클러스터를 대상으로 하는 도구 호출은 다음과 같습니다:
{
"cluster": "staging",
"index": "logs-*",
"body": {
"query": {
"match_all": {}
}
}
}MCP 서버 인증 (HTTP 전송 전용)
HTTP 기반 전송(SSE 또는 Streamable HTTP)으로 MCP 서버를 실행할 때 Bearer 토큰 인증을 활성화하여 무단 액세스로부터 서버를 보호할 수 있습니다.
MCP_API_KEY: MCP 서버 인증을 위한 API 키입니다. 클라이언트는Authorization: Bearer <MCP_API_KEY>헤더를 포함해야 합니다.
중요한 보안 참고 사항:
인증은 HTTP 전송(
sse,streamable-http)에 만 적용됩니다.stdio전송은 로컬 프로세스 통신을 사용하므로 인증이 필요하지 않습니다.MCP_API_KEY가 설정되지 않은 경우 MCP 서버는 인증 없이 액세스할 수 있습니다. 이는 네트워크를 통해 서버를 노출할 때 보안 위험이 있습니다.HTTP 전송을 사용하는 프로덕션 배포의 경우 항상
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"고위험 작업 비활성화
DISABLE_HIGH_RISK_OPERATIONS: 모든 쓰기 작업을 비활성화하려면true로 설정합니다 (기본값:false)DISABLE_OPERATIONS: 비활성화할 특정 작업의 쉼표로 구분된 목록 (선택 사항, 설정하지 않으면 기본 쓰기 작업 목록 사용)
DISABLE_HIGH_RISK_OPERATIONS가 true로 설정되면 쓰기 작업을 수행하는 모든 MCP 도구가 MCP 클라이언트에서 완전히 숨겨집니다. 이 모드에서는 다음 MCP 도구가 기본적으로 비활성화됩니다.
인덱스 작업:
create_indexdelete_index
문서 작업:
index_documentdelete_documentdelete_by_query
데이터 스트림 작업:
create_data_streamdelete_data_stream
별칭 작업:
put_aliasdelete_alias
일반 API 작업:
general_api_request
선택적으로 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"GCF 응답 인코딩 (선택 사항)
모델이 읽는 콘텐츠 블록에서 도구 결과 페이로드를 GCF(Graph Compact Format)로 직렬화하도록 선택할 수 있습니다. GCF는 토큰 최적화된 와이어 형식으로, Elasticsearch가 반환하는 크고 균일한 레코드 집합(검색 히트, 집계 버킷, 매핑)을 가장 잘 압축합니다. 대표적인 응답에서 간결한 JSON보다 약 39% 적은 토큰을 사용합니다(검색 히트의 경우 40%), 무손실로 압축됩니다.
export RESPONSE_FORMAT=gcfstructuredContent는 변경 없이 유지되므로 도구의 선언된 출력 스키마가 여전히 검증되고 비모델 클라이언트는 계속 JSON을 수신합니다. 모델이 보는 텍스트 블록만 다시 인코딩됩니다. 인코딩은 실패에 안전합니다. GCF의 표준 int64 숫자 도메인을 벗어나는 값(GCF가 조용히 근사하는 대신 거부함)을 포함한 모든 오류는 원래 JSON 결과를 그대로 두므로 인코딩으로 인해 도구 호출이 누락되지 않습니다. RESPONSE_FORMAT이 설정되지 않은 경우 기본 동작은 변경되지 않습니다.
토큰 비교를 재현하려면: uv run --with tiktoken python benchmarks/gcf_benchmark.py.
Elasticsearch/OpenSearch 클러스터 시작
Docker Compose를 사용하여 Elasticsearch/OpenSearch 클러스터를 시작합니다:
# For Elasticsearch
docker-compose -f docker-compose-elasticsearch.yml up -d
# For OpenSearch
docker-compose -f docker-compose-opensearch.yml up -d기본 Elasticsearch 사용자 이름은 elastic이고 비밀번호는 test123입니다. 기본 OpenSearch 사용자 이름은 admin이고 비밀번호는 admin입니다.
http://localhost:5601에서 Kibana/OpenSearch Dashboards에 액세스할 수 있습니다.
Stdio
옵션 1: uvx 사용
uvx를 사용하면 PyPI에서 패키지가 자동으로 설치되므로 로컬에 저장소를 클론할 필요가 없습니다. Claude Desktop의 구성 파일 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"
}
}
}
}옵션 2: 로컬 개발에 uv 사용
uv를 사용하려면 로컬에 저장소를 클론하고 소스 코드 경로를 지정해야 합니다. 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
옵션 1: 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옵션 2: 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 /sseStreamable HTTP
옵션 1: 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옵션 2: 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호환성
MCP 서버는 Elasticsearch 7.x, 8.x 및 9.x와 호환됩니다. 기본적으로 Elasticsearch 8.x 클라이언트(접미사 없음)를 사용합니다.
MCP 서버 | 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 클라이언트를 사용하려면 elasticsearch-mcp-server-es7 변형을 실행하세요. Elasticsearch 9.x의 경우 elasticsearch-mcp-server-es9를 사용하세요. 예:
uvx elasticsearch-mcp-server-es7다른 Elasticsearch 변형(예: 7.x 또는 9.x)을 로컬에서 실행하려면 pyproject.toml의 elasticsearch 종속성 버전을 업데이트한 다음 서버를 시작하세요:
uv run src/server.py elasticsearch-mcp-serverKubernetes 배포
Docker 이미지는 ghcr.io/cr7258/elasticsearch-mcp-server에 게시되며 Helm 차트는 oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server 저장소에서 OCI 아티팩트로 사용할 수 있습니다.
전체 설치 지침, 구성 참조 및 사용 예제는 **Helm 차트 README**를 참조하세요.
라이선스
이 프로젝트는 Apache License Version 2.0에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
Available Tools
20 toolsanalyze_textB
Analyze text to see how it would be tokenized.
Use this tool to understand how Elasticsearch/OpenSearch tokenizes and transforms text using analyzers. This is essential for debugging search queries and understanding why certain documents match or don't match.
Inputs: text (required), index, filter, cluster, +5 more. Returns: object
create_data_streamB
Create a new data stream.
This creates a new data stream with the specified name. The data stream must have a matching index template before creation.
Inputs: name (required), cluster. Returns: object
create_indexC
Create a new index.
Inputs: index (required), body, cluster. Returns: object
delete_aliasC
Delete an alias for a specific index.
Inputs: name (required), index (required), cluster. Returns: object
delete_by_queryC
Deletes documents matching the provided query.
Inputs: body (required), index (required), cluster. Returns: object
delete_data_streamA
Delete one or more data streams.
Permanently deletes the specified data streams and all their backing indices.
Inputs: name (required), cluster. Returns: object
delete_documentC
Delete a document by ID.
Inputs: id (required), index (required), cluster. Returns: object
delete_indexC
Delete an index.
Inputs: index (required), cluster. Returns: object
general_api_requestA
Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.
Inputs: path (required), method (required), body, params, +1 more.
get_aliasC
Get alias information for a specific index.
Inputs: index (required), cluster. Returns: object
get_cluster_healthC
Returns basic information about the health of the cluster.
Inputs: cluster. Returns: object
get_cluster_statsB
Returns high-level overview of cluster statistics.
Inputs: cluster. Returns: object
get_data_streamC
Get information about one or more data streams.
Retrieves configuration, mappings, settings, and other information about the specified data streams.
Inputs: name, cluster. Returns: object
get_documentC
Get a document by ID.
Inputs: id (required), index (required), cluster. Returns: object
get_indexB
Returns information (mappings, settings, aliases) about one or more indices.
Inputs: index (required), cluster. Returns: object
index_documentC
Creates or updates a document in the index.
Inputs: index (required), document (required), id, cluster. Returns: object
list_aliasesB
List all aliases.
Inputs: cluster. Returns: result
list_indicesC
List all indices.
Inputs: cluster. Returns: result
put_aliasC
Create or update an alias for a specific index.
Inputs: body (required), name (required), index (required), cluster. Returns: object
search_documentsC
Search for documents.
Inputs: body (required), index (required), cluster. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a clearly distinct resource and action (index, document, alias, data stream, cluster, analysis, or generic API). Overlaps like get_index vs list_indices and get_alias vs list_aliases are cleanly separated by specificity. The general_api_request fallback is explicitly scoped to APIs without dedicated tools, so it does not create real misselection risk.
Tools follow a consistent snake_case verb_noun convention (create_index, delete_document, get_cluster_health, put_alias, etc.). The only minor exception is general_api_request, but it still fits the overall readable naming style. There is no mixing of camelCase or conflicting verb patterns.
At 20 tools, the surface is slightly heavy by the usual 3–15 guideline, but Elasticsearch is a broad domain and each tool covers a meaningful resource area. The set avoids extreme bloat and does not include redundant operations.
Core CRUD and lifecycle coverage exists for indices, documents, aliases, data streams, and cluster inspection, with search and text analysis included. Notable gaps remain—such as dedicated index template management (required for data streams), bulk operations, and update-by-query—but the general_api_request tool provides a workaround for any missing API.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with Elasticsearch clusters, allowing them to manage indices and execute search queries using natural language.2-
- AlicenseBqualityDmaintenanceConnects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.4Apache 2.0
- FlicenseBqualityDmaintenanceConnects to Elasticsearch clusters through the Model Context Protocol, enabling natural language querying and management of Elasticsearch data. Provides tools to search indices, list available indices, and retrieve index mappings.3-
- AlicenseBqualityDmaintenanceEnables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.1017 npmMIT