Elasticsearch Mcp Server

io.github.cr7258由 GitHub 账号 cr7258 发布v2.0.15更新于 Nov 10, 2026

MCP server for interacting with Elasticsearch

概览

AI 生成的概览

本地运行的 MCP 服务器,让助手通过专用工具搜索、写入和管理 Elasticsearch 或 OpenSearch 集群。

可以做什么
  • 搜索、读取、创建、更新和删除文档,包括按查询批量删除
  • 列出、查看、创建和删除索引与数据流
  • 管理别名,并用指定分析器分析文本
  • 查看集群健康状态和统计信息
  • 对没有专用工具的接口发送任意 API 请求
  • 在多个命名集群之间按调用指定目标
适用场景
适合需要让助手探查或查询 Elasticsearch、OpenSearch 集群、调试搜索查询与映射,或进行日常索引和文档维护的场景。也适合配置了多个命名集群(如生产与预发)并希望助手按需选择目标的部署。
运行要求
以 Python 包形式在本地运行,通常用 uvx 或 uv 启动。需要可访问的 Elasticsearch 或 OpenSearch 地址(ELASTICSEARCH_HOSTS 或 OPENSEARCH_HOSTS)以及凭据:ELASTICSEARCH_API_KEY,或 ELASTICSEARCH_USERNAME 配合 ELASTICSEARCH_PASSWORD。可选配置包括多集群、默认集群、证书校验、请求超时和代理。
安装前请注意
凭据通过环境变量传入,请勿写入共享配置文件。多个工具会写入或删除数据,例如 delete_index、delete_document、delete_by_query 和 general_api_request;可用 DISABLE_HIGH_RISK_OPERATIONS 或 DISABLE_OPERATIONS 隐藏这些工具。证书校验默认关闭,会削弱 TLS 保护。若改用 HTTP 传输方式,务必设置 MCP_API_KEY,否则服务器在网络中无鉴权可访问。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Elasticsearch Mcp Server,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

Elasticsearch/OpenSearch MCP Server

[MseeP.ai Security Assessment Badge]

[Trust Score]

Overview

A Model Context Protocol (MCP) server implementation that provides Elasticsearch and OpenSearch interaction. This server enables searching documents, analyzing indices, and managing cluster through a set of tools.

[Elasticsearch MCP Server]

Demo

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

Features

General Operations

  • general_api_request: Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.

Index Operations

  • list_indices: List all indices.
  • get_index: Returns information (mappings, settings, aliases) about one or more indices.
  • create_index: Create a new index.
  • delete_index: Delete an index.
  • create_data_stream: Create a new data stream (requires matching index template).
  • get_data_stream: Get information about one or more data streams.
  • delete_data_stream: Delete one or more data streams and their backing indices.

Document Operations

  • search_documents: Search for documents.
  • index_document: Creates or updates a document in the index.
  • get_document: Get a document by ID.
  • delete_document: Delete a document by ID.
  • delete_by_query: Deletes documents matching the provided query.

Cluster Operations

  • get_cluster_health: Returns basic information about the health of the cluster.
  • get_cluster_stats: Returns high-level overview of cluster statistics.

Alias Operations

  • list_aliases: List all aliases.
  • get_alias: Get alias information for a specific index.
  • put_alias: Create or update an alias for a specific index.
  • delete_alias: Delete an alias for a specific index.

Analyzer Operations

  • analyze_text: Analyze text using a specified analyzer or custom analysis chain. Useful for debugging search queries and understanding how text is tokenized.

Configure Environment Variables

The MCP server supports the following environment variables:

Basic Authentication (Username/Password)

  • ELASTICSEARCH_USERNAME: Username for basic authentication
  • ELASTICSEARCH_PASSWORD: Password for basic authentication
  • OPENSEARCH_USERNAME: Username for OpenSearch basic authentication
  • OPENSEARCH_PASSWORD: Password for OpenSearch basic authentication

API Key Authentication (Elasticsearch only) - Recommended

Connection Settings

  • ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: Comma-separated list of hosts (default: https://localhost:9200)
  • ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS: Inline JSON object for named cluster configurations. When set, tools can target a specific cluster with the optional cluster parameter.
  • ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE: Path to a JSON file with the clusters object. Recommended when the configuration is embedded inside another JSON file (e.g. the MCP client config) because it avoids JSON-in-JSON escaping. Takes precedence over the inline variable when both are set.
  • DEFAULT_CLUSTER: Default cluster name to use when multi-cluster configuration is set and a tool call omits cluster (defaults to the first configured cluster).
  • VERIFY_CERTS: Whether to verify SSL certificates (default: false)
  • REQUEST_TIMEOUT: Request timeout in seconds (optional, uses client default if not set)
  • ELASTICSEARCH_PROXY / OPENSEARCH_PROXY: Route all requests through a proxy (optional). Supported schemes are http://, https://, socks5:// and socks5h://, e.g. socks5h://127.0.0.1:1080 for an SSH dynamic port forward (ssh -D 1080 bastion). Use socks5h when the cluster host name only resolves on the proxy side. In a multi-cluster configuration, set proxy per cluster; it overrides the environment variable.

Multiple Cluster Configuration

By default, the server uses a single Elasticsearch cluster from ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD, and ELASTICSEARCH_API_KEY, or a single OpenSearch cluster from OPENSEARCH_HOSTS, OPENSEARCH_USERNAME, and OPENSEARCH_PASSWORD. To configure multiple named clusters, set ELASTICSEARCH_CLUSTERS (or OPENSEARCH_CLUSTERS) to a JSON object inside the MCP server configuration. Because the value is a JSON string embedded in another JSON file, the inner quotes need to be escaped:

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

For better readability, point ELASTICSEARCH_CLUSTERS_FILE (or OPENSEARCH_CLUSTERS_FILE) at a standalone JSON file instead. The value is just a path so it avoids the JSON-in-JSON escaping:

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:

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>",    "proxy": "socks5h://127.0.0.1:1080"  }}

Here only staging is reached through a SOCKS proxy, prod connects directly.

Every tool accepts an optional cluster parameter. If omitted, the server uses DEFAULT_CLUSTER. When DEFAULT_CLUSTER is not set, the first cluster in the JSON object is used as the default. A tool call targeting a specific cluster looks like:

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

MCP Server Authentication (HTTP Transports Only)

When running the MCP server with HTTP-based transports (SSE or Streamable HTTP), you can enable Bearer token authentication to protect the server from unauthorized access.

  • MCP_API_KEY: API key for MCP server authentication. Clients must include Authorization: Bearer <MCP_API_KEY> header.

Important Security Notes:

  • Authentication is only applicable for HTTP transports (sse, streamable-http). The stdio transport uses local process communication and doesn't require authentication.
  • If MCP_API_KEY is not set, the MCP server will be accessible without authentication. This is a security risk when exposing the server over a network.
  • For production deployments with HTTP transports, always set MCP_API_KEY.
bash
# Generate a secure API key (example using openssl)export MCP_API_KEY=$(openssl rand -base64 32)
# Or set a custom API keyexport MCP_API_KEY="your-secure-api-key-here"

Disable High-Risk Operations

  • DISABLE_HIGH_RISK_OPERATIONS: Set to true to disable all write operations (default: false)
  • DISABLE_OPERATIONS: Comma-separated list of specific operations to disable (optional, uses default write operations list if not set)

When DISABLE_HIGH_RISK_OPERATIONS is set to true, all MCP tools that perform write operations are completely hidden from the MCP client. In this mode, the following MCP tools are disabled by default.

  • Index Operations:

    • create_index
    • delete_index
  • Document Operations:

    • index_document
    • delete_document
    • delete_by_query
  • Data Stream Operations:

    • create_data_stream
    • delete_data_stream
  • Alias Operations:

    • put_alias
    • delete_alias
  • General API Operations:

    • general_api_request

Optionally, you can specify a comma-separated list of operations to disable in the DISABLE_OPERATIONS environment variable.

bash
# Disable High-Risk Operationsexport DISABLE_HIGH_RISK_OPERATIONS=true# Disable specific operations onlyexport DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"

GCF Response Encoding (optional)

Opt in to serialize tool-result payloads as GCF (Graph Compact Format), a token-optimized wire format, in the content block the model reads. Elasticsearch returns large, uniform record sets (search hits, aggregation buckets, mappings), the shape GCF compacts best: on representative responses it is ~39% fewer tokens than compact JSON (40% on search hits), losslessly.

bash
export RESPONSE_FORMAT=gcf

structuredContent is preserved unchanged, so a tool's declared output schema still validates and any non-model client keeps receiving JSON; only the model-facing text block is re-encoded. Encoding is fail-safe: any error, including a value outside GCF's canonical int64 numeric domain (which GCF rejects rather than silently approximating), leaves the original JSON result untouched, so a tool call is never dropped over encoding. Default behavior is unchanged when RESPONSE_FORMAT is unset.

Reproduce the token comparison: uv run --with tiktoken python benchmarks/gcf_benchmark.py.

Start Elasticsearch/OpenSearch Cluster

Start the Elasticsearch/OpenSearch cluster using Docker Compose:

bash
# For Elasticsearchdocker-compose -f docker-compose-elasticsearch.yml up -d
# For OpenSearchdocker-compose -f docker-compose-opensearch.yml up -d

The default Elasticsearch username is elastic and password is test123. The default OpenSearch username is admin and password is admin.

You can access Kibana/OpenSearch Dashboards from http://localhost:5601.

Stdio

Option 1: Using uvx

Using uvx will automatically install the package from PyPI, no need to clone the repository locally. Add the following configuration to 's config file claude_desktop_config.json.

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

Option 2: Using uv with local development

Using uv requires cloning the repository locally and specifying the path to the source code. Add the following configuration to Claude Desktop's config file claude_desktop_config.json.

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

Option 1: Using uvx

bash
# 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/sseuvx elasticsearch-mcp-server --transport sse
# The host, port, and path can be specified using the --host, --port, and --path optionsuvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Option 2: Using uv

bash
# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sseuv run src/server.py elasticsearch-mcp-server --transport sse
# The host, port, and path can be specified using the --host, --port, and --path optionsuv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Streamable HTTP

Option 1: Using uvx

bash
# 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/mcpuvx elasticsearch-mcp-server --transport streamable-http
# The host, port, and path can be specified using the --host, --port, and --path optionsuvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Option 2: Using uv

bash
# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcpuv run src/server.py elasticsearch-mcp-server --transport streamable-http
# The host, port, and path can be specified using the --host, --port, and --path optionsuv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Compatibility

The MCP server is compatible with Elasticsearch 7.x, 8.x, and 9.x. By default, it uses the Elasticsearch 8.x client (without a suffix).

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

To use the Elasticsearch 7.x client, run the elasticsearch-mcp-server-es7 variant. For Elasticsearch 9.x, use elasticsearch-mcp-server-es9. For example:

bash
uvx elasticsearch-mcp-server-es7

If you want to run different Elasticsearch variants (e.g., 7.x or 9.x) locally, simply update the elasticsearch dependency version in pyproject.toml, then start the server with:

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

Kubernetes Deployment

The Docker image is published to ghcr.io/cr7258/elasticsearch-mcp-server and the Helm chart is available as an OCI artifact at oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server repository.

For full installation instructions, configuration reference, and usage examples see the Helm chart README.

License

This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.

来源:README.md,提交 90ae064

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v2.0.15最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分