Elasticsearch/OpenSearch MCP Server

Name: Elasticsearch/OpenSearch MCP Server
Author: cr7258

本地服务

github.com/cr7258数据库3141 周前更新

代码仓库

关于 Elasticsearch/OpenSearch MCP Server

Elasticsearch/OpenSearch MCP Server 是一个 MCP 服务，用于通过工具与 Elasticsearch 和 OpenSearch 集群交互。它面向需要通过 AI 助手检索文档、分析索引和管理集群的用户，并支持多集群配置与只读模式下的写操作禁用。

主要功能

01索引、文档、别名与数据流的增删查操作
02集群健康与统计信息查询
03analyze_text 文本分析工具，用于调试搜索查询
04通过 general_api_request 调用任意 HTTP API
05支持多集群命名配置与默认集群
06可禁用高风险写操作

适用场景

01通过 AI 助手检索和查看 Elasticsearch 索引中的文档
02排查搜索查询的分词结果
03在受限模式下查看集群状态而不修改数据

#elasticsearch #mcp-server #data-management

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "elasticsearch": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "<ELASTICSEARCH_HOSTS>",
        "ELASTICSEARCH_API_KEY": "<ELASTICSEARCH_API_KEY>",
        "ELASTICSEARCH_USERNAME": "<ELASTICSEARCH_USERNAME>",
        "ELASTICSEARCH_PASSWORD": "<ELASTICSEARCH_PASSWORD>",
        "ELASTICSEARCH_VERIFY_CERTS": "<ELASTICSEARCH_VERIFY_CERTS>"
      }
    }
  }
}

启动命令uvx elasticsearch-mcp-server

需要配置的环境变量

ELASTICSEARCH_HOSTSComma-separated list of Elasticsearch hosts (e.g., https://localhost:9200)

ELASTICSEARCH_API_KEY密钥API key for Elasticsearch or Elastic Cloud authentication (recommended)

ELASTICSEARCH_USERNAMEUsername for basic authentication (alternative to API key)

ELASTICSEARCH_PASSWORD密钥Password for basic authentication (used with ELASTICSEARCH_USERNAME)

ELASTICSEARCH_VERIFY_CERTSWhether to verify SSL certificates (true/false)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypielasticsearch-mcp-server2.0.15stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Elasticsearch/OpenSearch MCP 服务

概述

一种 Model Context Protocol（MCP）服务实现，可与 Elasticsearch 和 OpenSearch 交互。此服务提供一组工具，可用于搜索文档、分析索引和管理集群。

演示

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_index
- delete_index
文档操作：
- index_document
- delete_document
- delete_by_query
数据流操作：
- create_data_stream
- delete_data_stream
别名操作：
- put_alias
- delete_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），这是一种经过 token 优化的传输格式，放在模型读取的内容块中。Elasticsearch 会返回大型、结构统一的记录集（搜索命中项、聚合桶、映射），这正是 GCF 最擅长压缩的数据形态：在有代表性的响应中，无损压缩后比紧凑 JSON 少约 39% 的 token（搜索命中项少 40%）。

export RESPONSE_FORMAT=gcf

structuredContent 会原样保留，因此工具声明的输出架构仍可通过验证，任何非模型客户端也仍会收到 JSON；只有面向模型的文本块会重新编码。编码采用故障安全方式：出现任何错误时（包括值超出 GCF 的规范 int64 数值范围；GCF 会拒绝此类值，而不会静默近似），都会保留原始 JSON 结果，因此工具调用绝不会因编码而被丢弃。未设置 RESPONSE_FORMAT 时，默认行为不变。

重现 token 对比：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 安装软件包，无需在本地克隆仓库。将以下配置添加到 ‘s 配置文件 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 /sse

Streamable 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-server

Kubernetes 部署

Docker 镜像已发布至 ghcr.io/cr7258/elasticsearch-mcp-server，Helm chart 可作为 OCI 工件从 oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server 仓库获取。

完整的安装说明、配置参考和使用示例，请参阅 Helm chart README。

许可证

本项目采用 Apache License Version 2.0 许可，详情请参阅 LICENSE 文件。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Elasticsearch/OpenSearch MCP Server

关于 Elasticsearch/OpenSearch MCP Server

主要功能

适用场景

配置

工具

详细介绍

Elasticsearch/OpenSearch MCP 服务

概述

演示

功能

常规操作

索引操作

文档操作

集群操作

别名操作

分析器操作

配置环境变量

基本身份验证（用户名/密码）

API 密钥身份验证（仅限 Elasticsearch）- 推荐

连接设置

多集群配置

MCP 服务身份验证（仅限 HTTP 传输方式）

禁用高风险操作

GCF 响应编码（可选）

启动 Elasticsearch/OpenSearch 集群

Stdio

选项 1：使用 uvx

选项 2：使用 uv 进行本地开发

SSE

选项 1：使用 uvx

选项 2：使用 uv

Streamable HTTP

选项 1：使用 uvx

选项 2：使用 uv

兼容性

Kubernetes 部署

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？