MCP Es

🚀 Elasticsearch MCP Server

このリポジトリには、研究と評価を目的とした実験的な機能が含まれており、本番環境での使用には適していません。

Model Context Protocol (MCP) を使用して、任意の MCP クライアント（Claude Desktop など）から直接 Elasticsearch データに接続できます。

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

✨ 主な機能

• list_indices：利用可能なすべての Elasticsearch インデックスをリストする
• get_mappings：特定の Elasticsearch インデックスのフィールドマッピングを取得する
• search：指定されたクエリ DSL で Elasticsearch 検索を実行する
• get_shards：すべてまたは特定のインデックスのシャード情報を取得する

📦 インストール

前提条件

• Elasticsearch インスタンス
• Elasticsearch 認証資格情報（API キーまたはユーザー名/パスワード）
• MCP クライアント（例: Claude Desktop）

デモ

https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c

公開された NPM パッケージを使用する

💡 使用建议

Elasticsearch MCP Server を使用する最も簡単な方法は、公開された npm パッケージを通じることです。

1. MCP クライアントを構成する

   • MCP クライアントを開きます。MCP クライアントのリストを参照してください。ここでは Claude Desktop を構成します。
   • 設定 > 開発者 > MCP サーバーに移動します。
   • 設定を編集をクリックし、次の構成で新しい MCP サーバーを追加します。

   {
     "mcpServers": {
       "elasticsearch-mcp-server": {
         "command": "npx",
         "args": [
           "-y",
           "@elastic/mcp-server-elasticsearch"
         ],
         "env": {
           "ES_URL": "your-elasticsearch-url",
           "ES_API_KEY": "your-api-key"
         }
       }
     }
   }
   

2. 会話を開始する

   • MCP クライアントで新しい会話を開きます。
   • MCP サーバーは自動的に接続されるはずです。
   • これで Elasticsearch データに関する質問をすることができます。

構成オプション

Elasticsearch MCP Server は、Elasticsearch に接続するための構成オプションをサポートしています。

⚠️ 重要提示

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

ローカルでの開発

⚠️ 重要提示

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

1. 正しい Node.js バージョンを使用する

   nvm use
   

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

   npm install
   

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

   npm run build
   

4. Claude Desktop アプリでローカルで実行する

   • Claude Desktop アプリを開きます。
   • 設定 > 開発者 > MCP サーバーに移動します。
   • 設定を編集をクリックし、次の構成で新しい MCP サーバーを追加します。

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

5. MCP インスペクターでデバッグする

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

   これにより MCP インスペクターが起動し、リクエストのデバッグと分析が可能になります。次のような表示がされるはずです。

   Starting MCP inspector...
   Proxy server listening on port 3000
   
   🔍 MCP Inspector is up and running at http://localhost:5173 🚀
   

💻 使用例

💡 使用建议

ここでは、MCP クライアントで試すことができる自然言語クエリの例をいくつか紹介します。

• "Elasticsearch クラスターにどのようなインデックスがありますか？"
• "「products」インデックスのフィールドマッピングを表示してください。"
• "先月の 500 ドルを超えるすべての注文を見つけてください。"
• "最も多くの 5 つ星レビューを受けた商品はどれですか？"

📚 ドキュメント

動作原理

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

セキュリティのベストプラクティス

⚠️ 重要提示

クラスター管理者権限の使用を避けてください。限定されたスコープの専用 API キーを作成し、インデックスレベルで細かいアクセス制御を適用して、不正なデータアクセスを防止します。

データへのアクセスを制御するために、最小限の権限を持つ専用の Elasticsearch API キーを作成することができます。

POST /_security/api_key
{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": [
        "monitor"
      ],
      "indices": [
        {
          "names": [
            "index-1",
            "index-2",
            "index-pattern-*"
          ],
          "privileges": [
            "read",
            "view_index_metadata"
          ]
        }
      ]
    }
  }
}

トラブルシューティング

• MCP 構成が正しいことを確認してください。
• Elasticsearch URL がマシンからアクセス可能であることを確認してください。
• 認証資格情報（API キーまたはユーザー名/パスワード）に必要な権限があることを確認してください。
• カスタム CA を使用して SSL/TLS を使用する場合は、証明書のパスが正しく、ファイルが読み取り可能であることを確認してください。
• エラーメッセージをターミナル出力で確認してください。

問題が発生した場合は、GitHub リポジトリで問題を報告してください。

📄 ライセンス

このプロジェクトは、Apache License 2.0 の下でライセンスされています。

コントリビューション

コミュニティからのコントリビューションを歓迎します！ コントリビュートする方法の詳細については、Contributing Guidelines を参照してください。