Elasticsearch MCP Server

Elasticsearch MCP Server

英語 | 中国語

Claude Desktop、Cursor などの任意の MCP クライアントから Elasticsearch クラスターに直接接続するための MCP サーバーです。

このサーバーは、Model Context Protocol を使用してエージェントを Elasticsearch のデータに接続します。自然言語での会話を通じて、Elasticsearch のインデックスを操作できます。

デモ

機能の概要

利用可能な機能

クラスター管理

• elasticsearch_health：Elasticsearch クラスターのヘルスステータスを取得します。必要に応じてインデックスレベルの詳細も含められます。

インデックス操作

• list_indices：利用可能な Elasticsearch インデックスを一覧表示します。正規表現に対応しています。
• create_index：必要に応じて設定とマッピングを指定して、Elasticsearch インデックスを作成します。
• reindex：必要に応じてクエリとスクリプトを指定して、ソースインデックスからターゲットインデックスにデータを再インデックスします。

マッピング管理

• get_mappings：指定した Elasticsearch インデックスのフィールドマッピングを取得します。
• create_mapping：Elasticsearch インデックスのマッピング構造を作成または更新します。

検索とデータ操作

• search：指定したクエリ DSL で Elasticsearch の検索を実行します。
• bulk：Elasticsearch インデックスにデータを一括登録します。

テンプレート管理

• create_index_template：インデックステンプレートを作成または更新します。
• get_index_template：インデックステンプレートの情報を取得します。
• delete_index_template：インデックステンプレートを削除します。

仕組み

1. MCP クライアントがリクエストを分析し、必要な Elasticsearch 操作を判断します。
2. MCP サーバーがこれらの操作（インデックスの一覧表示、マッピングの取得、検索の実行など）を行います。
3. MCP クライアントが結果を処理し、わかりやすい形式で表示します。

はじめに

前提条件

• Elasticsearch インスタンス
• Elasticsearch の認証情報（API キーまたはユーザー名とパスワード）
• MCP クライアント（例：Claude Desktop、Cursor）

インストールとセットアップ

公開済みの NPM パッケージを使用する

ヒント

Elasticsearch MCP Server を使用する最も簡単な方法は、公開済みの npm パッケージを利用することです。

1. MCP クライアントを設定する

   • MCP クライアントを開きます。MCP クライアントの一覧を参照してください。ここでは Claude Desktop を設定します。
   • Settings > Developer > MCP Servers に移動します。
   • Edit Config をクリックし、以下の設定で新しい MCP サーバーを追加します。

   {
     "mcpServers": {
       "elasticsearch-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "@awesome-ai/elasticsearch-mcp"
         ],
         "env": {
           "ES_HOST": "your-elasticsearch-host",
           "ES_API_KEY": "your-api-key"
         }
       }
     }
   }
   

2. 会話を開始する

   • MCP クライアントで新しい会話を開きます。
   • MCP サーバーが自動的に接続されます。
   • Elasticsearch のデータについて質問できるようになります。

設定オプション

Elasticsearch MCP Server は、Elasticsearch への接続に使用する設定オプションに対応しています。

メモ

認証には API キーを指定するか、ユーザー名とパスワードの両方を指定する必要があります。

環境変数	説明	必須
ES_HOST	Elasticsearch インスタンスの URL。単一の URL またはカンマ区切りの複数 URL に対応しています（従来の HOST にも対応）。	はい
ES_API_KEY	認証用の Elasticsearch API キー（従来の API_KEY にも対応）。	いいえ
ES_USERNAME	基本認証用の Elasticsearch ユーザー名（従来の USERNAME にも対応）。	いいえ
ES_PASSWORD	基本認証用の Elasticsearch パスワード（従来の PASSWORD にも対応）。	いいえ
ES_CA_CERT	Elasticsearch の SSL/TLS 用カスタム CA 証明書のパス（従来の CA_CERT にも対応）。	いいえ

複数 URL の設定

高可用性と負荷分散のため、複数の Elasticsearch ノードを設定できます。

{
  "mcpServers": {
    "elasticsearch-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@awesome-ai/elasticsearch-mcp"
      ],
      "env": {
        "ES_HOST": "https://es-node1:9200,https://es-node2:9200,https://es-node3:9200",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

クライアントは、設定されたノード間のフェイルオーバーと負荷分散を自動的に処理します。

ローカル開発

メモ

MCP サーバーを変更または拡張する場合は、以下のローカル開発手順に従ってください。

1. 適切な Node.js バージョンを使用する

   nvm use
   

2. 依存関係をインストールする

   npm install
   

3. プロジェクトをビルドする

   npm run build
   

4. Claude Desktop App でローカル実行する

   • Claude Desktop App を開きます
   • Settings > Developer > MCP Servers に移動します
   • Edit Config をクリックし、以下の設定で新しい MCP サーバーを追加します：

   {
     "mcpServers": {
       "elasticsearch-mcp": {
         "command": "node",
         "args": [
           "/path/to/your/project/dist/index.js"
         ],
         "env": {
           "ES_HOST": "your-elasticsearch-host",
           "ES_API_KEY": "your-api-key"
         }
       }
     }
   }
   

5. Cursor Editor でローカル実行する

   • Cursor Editor を開きます
   • Cursor Settings > MCP に移動します
   • Add new global MCP Server をクリックし、以下の設定で新しい MCP サーバーを追加します：

   {
     "mcpServers": {
       "elasticsearch-mcp": {
         "command": "node",
         "args": [
           "/path/to/your/project/dist/index.js"
         ],
         "env": {
           "ES_HOST": "your-elasticsearch-host",
           "ES_API_KEY": "your-api-key"
         }
       }
     }
   }
   

6. MCP Inspector でデバッグする

   ES_HOST=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspector
   

   これにより MCP Inspector が起動し、リクエストをデバッグして分析できます。次のように表示されます：

   Starting MCP inspector...
   ⚙️ Proxy server listening on port 6277
   🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
   

クエリの例

ヒント

MCP クライアントで試せる自然言語のクエリをいくつか紹介します。

クラスター管理

• 「Elasticsearch クラスターのヘルスステータスはどうなっていますか？」
• 「クラスターにはアクティブなノードがいくつありますか？」

インデックス操作

• 「Elasticsearch クラスターにはどのインデックスがありますか？」
• 「シャード数 3、レプリカ数 1 で、users という新しいインデックスを作成してください。」
• 「old_index から new_index にデータを再インデックスしてください。」

マッピング管理

• 「products インデックスのフィールドマッピングを表示してください。」
• 「products インデックスに、tags というキーワード型のフィールドを追加してください。」

検索とデータ操作

• 「先月の 500 ドルを超える注文をすべて検索してください。」
• 「最も多くの 5 つ星レビューを受けた商品はどれですか？」
• 「これらの顧客レコードを customers インデックスに一括インポートしてください。」

テンプレート管理

• 「パターン logs-* を使って、ログ用のインデックステンプレートを作成してください。」
• 「すべてのインデックステンプレートを表示してください。」
• 「outdated_template インデックステンプレートを削除してください。」

問題が発生した場合は、GitHub リポジトリでお気軽に issue を作成してください。