Elasticsearch MCP Server
Elasticsearch/OpenSearch MCP 服务器
概述
一个模型上下文协议(MCP)服务器实现,提供 Elasticsearch 和 OpenSearch 交互能力。该服务器通过一组工具实现文档搜索、索引分析和集群管理。
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 嵌套 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 服务器配置中将 ELASTICSEARCH_CLUSTERS(或 OPENSEARCH_CLUSTERS)设置为 JSON 对象。由于该值是嵌入在另一个 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 嵌套 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),这是一种面向模型读取的内容块中的令牌优化线格式。Elasticsearch 返回大量统一的记录集(搜索命中、聚合桶、映射),这正是 GCF 压缩效果最好的场景:在代表性响应上,它比紧凑 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 chart 以 OCI 制品形式提供,位于 oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server 仓库。
有关完整的安装说明、配置参考和使用示例,请参阅 Helm chart 自述文件。
许可证
本项目根据 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