Elasticsearch MCP Server

Elasticsearch MCP サーバー

これは、Elasticsearch を使用して物件データを検索、分析するためのインターフェースを提供する、Python ベースの MCP（Model Control Protocol）サーバーです。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 キーを作成します（詳しくはデータ取り込みの 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：Rerank 推論エンドポイント 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*）

ライセンス

Copyright Elasticsearch B.V. and contributors SPDX-License-Identifier: Apache-2.0