使用说明

项目简介

Elasticsearch 7.x MCP服务器是一个基于Model Context Protocol (MCP) 构建的应用后端，旨在为大型语言模型（LLM）客户端提供与Elasticsearch 7.x 集群交互的标准接口。通过此服务器，LLM应用可以安全、便捷地访问和利用Elasticsearch 7.x 的强大搜索和数据分析能力。

主要功能点

Elasticsearch 7.x 兼容: 专为Elasticsearch 7.x 版本设计，确保稳定可靠的连接和操作。
资源检索: 支持全面的Elasticsearch 搜索功能，包括关键词匹配、布尔查询、过滤、排序、高亮显示等。
聚合分析: 支持Elasticsearch 的聚合查询，帮助LLM应用进行数据统计和分析。
MCP 协议标准: 遵循MCP 协议，易于与各种MCP 客户端集成。
工具化API: 通过工具化的API ('es-ping', 'es-info', 'es-search') 暴露Elasticsearch 功能，方便LLM 调用。
灵活配置: 支持通过环境变量配置Elasticsearch 连接信息和MCP 服务器端口。
Docker Compose 部署: 提供Docker Compose 部署方案，一键启动包含Elasticsearch 集群和MCP 服务器的完整环境。

安装步骤

手动安装 (推荐):
- 确保已安装 Python 3.10 或更高版本。
- 克隆或下载此仓库到本地。
- 在仓库根目录下，打开终端并运行命令安装：
```
pip install -e .
```

通过 Smithery 安装 (如果使用 Claude Desktop):

如果您使用 Claude Desktop 等 Smithery 客户端，可以使用以下命令自动安装：

npx -y @smithery/cli install @imlewc/elasticsearch7-mcp-server --client claude

服务器配置

MCP 客户端需要配置以下信息以连接到 Elasticsearch 7.x MCP 服务器。配置信息为 JSON 格式，示例如下：

{
  "serverName": "elasticsearch7-mcp-server",
  "command": "elasticsearch7-mcp-server",
  "args": [],
  "env": {
    "ELASTIC_HOST": "http://localhost:9200",
    "ELASTIC_USERNAME": "your_elasticsearch_username",
    "ELASTIC_PASSWORD": "your_elasticsearch_password",
    "MCP_PORT": "9999"
  }
}

配置参数说明:

'serverName': 服务器名称，可以自定义，用于在MCP客户端中标识该服务器。例如 '"elasticsearch7-mcp-server"'。
'command': 启动 MCP 服务器的命令。安装成功后，可以直接使用 'elasticsearch7-mcp-server' 命令启动服务器。
'args': 启动命令的参数，本服务器无需额外启动参数，因此配置为空数组 '[]'。
'env': 环境变量配置，用于配置 Elasticsearch 连接信息和 MCP 服务器端口。
- 'ELASTIC_HOST': Elasticsearch 主机地址，例如 '"http://localhost:9200"'。
- 'ELASTIC_USERNAME': Elasticsearch 用户名 (如果 Elasticsearch 集群启用了安全认证)。
- 'ELASTIC_PASSWORD': Elasticsearch 密码 (如果 Elasticsearch 集群启用了安全认证)。
- 'MCP_PORT': (可选) MCP 服务器监听端口，默认为 '9999'。可以根据需要修改。

Docker Compose 部署配置:

如果您使用 Docker Compose 部署，请确保在 '.env' 文件中设置 'ELASTIC_PASSWORD' 环境变量。启动 Docker Compose 后，MCP 服务器将自动运行。

基本使用方法

启动 MCP 服务器:
- 手动安装: 在安装了 'elasticsearch7-mcp-server' 的 Python 环境中，直接运行命令 'elasticsearch7-mcp-server' 即可启动服务器。
- Docker Compose: 启动 Docker Compose 环境后，MCP 服务器会自动在 Docker 容器中运行。
使用 MCP 客户端连接:
- 在您的 LLM 应用或 MCP 客户端中，使用配置好的服务器连接信息 (JSON 配置) 连接到 MCP 服务器。
- 您可以使用任何 MCP 客户端库 (例如 'mcp-client-py' 等) 与服务器进行交互。

调用 Elasticsearch 工具:

连接成功后，您可以使用 MCP 客户端调用服务器提供的工具，例如 'es-ping' (检查连接), 'es-info' (获取集群信息), 'es-search' (执行搜索)。
以下 Python 代码示例展示了如何使用 'mcp-client-py' 客户端调用 'es-ping' 和 'es-search' 工具:

from mcp import MCPClient

client = MCPClient("localhost:9999") # 假设 MCP 服务器运行在本地 9999 端口

# 调用 es-ping 工具检查连接
ping_response = client.call("es-ping")
print(f"Ping response: {ping_response}")

# 调用 es-search 工具执行搜索
search_params = {
    "index": "your_index_name",
    "query": {
        "match": {
            "your_field_name": "search keywords"
        }
    }
}
search_response = client.call("es-search", search_params)
print(f"Search response: {search_response}")

请根据 API Documentation 中的描述，构建 'es-search' 工具的请求参数，以实现更复杂的搜索和聚合功能。

API Documentation

当前支持的 MCP 方法 (Tools):

'es-ping': 检查与 Elasticsearch 服务器的连接是否正常。
'es-info': 获取 Elasticsearch 集群的详细信息。
'es-search': 在 Elasticsearch 索引中搜索文档。支持所有 Elasticsearch 7.x 版本的搜索参数，包括查询 (query)、聚合 (aggs)、排序 (sort)、高亮 (highlight)、源字段过滤 (_source) 等。

Search API Examples

请参考仓库 README.md 文件中的 "Search API Examples" 部分，了解 'es-search' 工具的详细使用示例，包括基本搜索、聚合查询和高级搜索等。

关键词