Elasticsearch MCP Server

Elasticsearch MCP 服务

这是一个基于 Python 的 MCP（Model Control Protocol）服务，用于通过 Elasticsearch 搜索和分析房产数据。该服务已从 Jupyter notebook 转换为独立的 Python 脚本。

观看房产搜索系统的运行演示：

https://github.com/user-attachments/assets/df498631-fb16-4ba5-b1fd-c14670213d73

功能

• 房产搜索：使用多种条件搜索房产，包括：

  • 位置（支持地理编码）
  • 价格范围
  • 卧室／浴室数量
  • 建筑面积
  • 房产特色
  • 房产税和维护费用

• 地理编码集成：使用 Google Maps API 将位置字符串转换为地理坐标

• Elasticsearch 集成：

  • 连接到 Elasticsearch Serverless
  • 使用 ELSER（Elastic Learned Sparse Encoder）进行语义搜索
  • 使用 E5（multilingual-e5-small）提供额外的语义功能
  • 支持自定义搜索模板
  • 自动监控并唤醒推理端点

项目结构

.
├── data-ingestion/        # Scripts for setting up and populating Elasticsearch
│   ├── data/             # Local data directory for property data
│   ├── ingest-properties.py  # Main ingestion script
│   ├── requirements.txt   # Python dependencies
│   ├── setup.sh          # Setup script
│   └── README.md         # Data ingestion documentation
├── elastic_mcp_server.py  # Main MCP server
├── env_config.sh         # Environment configuration
├── env_config.template.sh # Environment configuration template
├── requirements.txt      # Python dependencies
└── README.md            # This file

数据摄取

运行 MCP 服务之前，需要设置并填充 Elasticsearch 实例中的房产数据。这由 data-ingestion 文件夹中的脚本处理。请按照 data-ingestion README 中的设置说明执行以下操作：

• 设置 Python 环境
• 配置 Elasticsearch
• 下载并摄取房产数据

将 API 密钥设为只读

数据摄取部分创建的密钥具有更广泛的服务端权限，例如创建索引和搜索模板脚本。你可以通过编辑现有密钥的安全权限，或创建一个具有以下权限的新密钥，进一步限制该 API 密钥：

{
  "mcp_server_read_only": {
    "cluster": [
      "monitor"
    ],
    "indices": [
      {
        "names": [
          "properties", "properties_raw"
        ],
        "privileges": [
          "read",
          "view_index_metadata"
        ],
        "allow_restricted_indices": false
      }
    ],
    "applications": [],
    "run_as": [],
    "metadata": {},
    "transient_metadata": {
      "enabled": true
    }
  }
}

要求

• Python => 3.10
• Elasticsearch Serverless 实例
• Google Maps API 密钥
• 必需的 Python 软件包（参见 requirements.txt）

设置所需服务

创建 Google Maps API 密钥

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用以下 API：
   • Geocoding API
   • Maps JavaScript API
4. 创建凭据：
   • 前往 "APIs & Services" > "Credentials"
   • 点击 "Create Credentials" > "API Key"
   • 复制生成的 API 密钥
5. （可选）将 API 密钥的使用范围限制为仅所需的 API

设置 Elasticsearch Serverless

1. 前往 Elastic Cloud
2. 注册或登录你的账户
3. 在 "Serverless projects" 下，选择 "Create serverless project"
4. 选择首选的云服务提供商和区域
5. 点击 "Create deployment"
6. 创建完成后，在 Kibana 的 "Getting Started" 中可以获取 Elastic URL
7. 创建具有所需权限的 API 密钥（详情请参见 Data Ingestion README）

环境变量

需要在 env_config.sh 中配置以下环境变量。可以在加载配置文件之前设置对应的环境变量，以覆盖推理端点 ID：

• ES_URL：Elasticsearch Serverless URL
• ES_API_KEY：Elasticsearch API 密钥
• GOOGLE_MAPS_API_KEY：Google Maps API 密钥
• PROPERTIES_SEARCH_TEMPLATE：搜索模板 ID（默认值："properties-search-template"）
• ELSER_INFERENCE_ID：ELSER 推理端点 ID（默认值：".elser-2-elasticsearch"）
• E5_INFERENCE_ID：E5 推理端点 ID（默认值：".multilingual-e5-small-elasticsearch"）
• RERANK_INFERENCE_ID：重排序推理端点 ID（默认值：".rerank-v1-elasticsearch"）
• ES_INDEX：Elasticsearch 索引名称（默认值："properties"）
• MCP_PORT：MCP 服务的端口号（默认值：8001）

覆盖推理端点 ID

可以在加载配置之前设置环境变量，以覆盖默认的推理端点 ID：

# Set custom inference endpoint IDs
export ELSER_INFERENCE_ID=".custom-elser-endpoint"
export E5_INFERENCE_ID=".custom-e5-endpoint"
export RERANK_INFERENCE_ID=".custom-rerank-endpoint"

# Source the config (will use your custom values)
source env_config.sh

设置

选项 1：Docker 设置

如需使用 Docker 进行容器化设置，请参阅 Docker 设置指南，了解以下内容的详细说明：

• 设置环境变量
• 使用 Docker Compose 运行
• 生产环境部署选项
• 容器管理命令

选项 2：手动设置

1. 克隆仓库：

git clone https://github.com/sunilemanjee/Elastic-Python-MCP-Server.git
cd Elastic-Python-MCP-Server

2. 如果尚未按照数据摄取说明创建和配置环境变量，请现在创建并配置：

# Copy the template file
cp env_config.template.sh env_config.sh

# Edit env_config.sh with your credentials
nano env_config.sh  # or use your preferred editor

3. 设置 Python 虚拟环境：

# Create virtual environment
python3.11 -m venv venv

# Activate virtual environment
source venv/bin/activate ##on macbook it may be .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

4. 加载环境变量：

source env_config.sh

运行服务

1. 运行服务：

./run_server.sh

服务默认会在端口 8001 上启动。你可以通过检查以下内容来确认服务正在运行：

curl -v http://localhost:8001/mcp

API 端点

该服务提供多个 MCP 工具，可供前端应用或其他 MCP 客户端调用：

1. wake_inference_endpoints：唤醒 ELSER 和 E5 推理端点（成功时返回 "Endpoints Awakened"）
2. get_properties_template_params：返回房产搜索模板所需的参数
3. geocode_location：将地点字符串转换为地理坐标
4. search_template：使用已配置的搜索模板搜索房产

搜索参数

搜索模板支持以下参数：

• query：主要搜索查询（必填）
• latitude：地理纬度坐标
• longitude：地理经度坐标
• bathrooms：浴室数量
• tax：房产税金额
• maintenance：维护费金额
• square_footage：房产面积
• home_price：最高房价
• features：房屋特点（例如，poolupdated kitchen*）

许可证

版权所有：Elasticsearch B.V. 及贡献者 SPDX-License-Identifier: Apache-2.0