Elasticsearch MCP Server

Elasticsearch MCP サーバー

注意

この MCP サーバーは非推奨となっており、今後は重大なセキュリティ更新のみが提供されます。 Elastic 9.2.0 以降および Elasticsearch Serverless プロジェクトで利用できる Elastic Agent Builder MCP endpoint に置き換えられました。

AI エージェント向け Elasticsearch MCP サーバーの使用

Elasticsearch MCP サーバーは、Model Context Protocol（MCP）を使用して、AI エージェントを Elasticsearch のデータに接続します。 これにより、Elasticsearch のインデックスと自然言語でやり取りできるようになり、カスタム API を使わずにエージェントがデータのクエリ、分析、取得を行えます。

以下の手順に従って、AWS Marketplace から Elasticsearch MCP サーバーのコンテナイメージをデプロイし、設定してください。

開始する前に

開始する前に、以下を用意してください。

• AWS 環境からアクセスできる Elasticsearch クラスター（バージョン 8.x または 9.x）
• Elasticsearch の認証情報：
  • API key、または
  • ユーザー名とパスワードの組み合わせ
• AWS 環境（たとえば、EC2 インスタンスまたはコンテナサービス）に Docker がインストールされ、実行されていること
• MCP クライアント（Claude Desktop、Cursor、VS Code、またはその他の MCP 互換ツールなど）が設定されていること
• デプロイ環境と Elasticsearch クラスター間のネットワーク接続

メモ

これらの手順は Elasticsearch MCP Server 0.4.0 以降に適用されます。 バージョン 0.3.1 以前については、v0.3.1 の READMEを参照してください。

Elasticsearch MCP サーバーをデプロイする

Elasticsearch MCP サーバーは、AWS Marketplace から入手できる Docker コンテナイメージとして提供されています。stdio プロトコル（クライアントとの直接接続用）または streamable-HTTP プロトコル（ウェブベースの統合用）を使用して実行できます。

プロトコルを選択する

サーバーは次の 2 つのプロトコルをサポートしています。

• stdio：MCP クライアントとサーバー間の直接通信です。クライアントが stdio をサポートし、同じ環境で実行される場合に使用してください。
• streamable-HTTP：ウェブ統合、ステートフルセッション、複数の同時接続クライアントに推奨される HTTP ベースのプロトコルです。

注記： Server-Sent Events（SSE）は非推奨です。代わりに streamable-HTTP を使用してください。

stdio プロトコルを設定する

MCP クライアントがサーバープロセスに直接接続する場合は、stdio プロトコルを使用してください。

stdio モード用の環境変数を設定する

以下の環境変数を設定してください。

• ES_URL：Elasticsearch クラスターの URL（例：https://your-cluster.es.amazonaws.com:9200）
• 認証には、次のいずれかの方法を使用します。
  • API キー：ES_API_KEY に Elasticsearch の API キーを設定します
  • Basic 認証：ES_USERNAME と ES_PASSWORD に Elasticsearch の認証情報を設定します
• （任意）ES_SSL_SKIP_VERIFY：Elasticsearch への接続時に SSL/TLS 証明書の検証をスキップするには、true に設定します。開発環境またはテスト環境でのみ使用してください。

stdio モードでコンテナを実行する

MCP サーバーを stdio モードで起動します。

docker run -i --rm \
  -e ES_URL \
  -e ES_API_KEY \
  docker.elastic.co/mcp/elasticsearch \
  stdio

Claude Desktop を設定する

この設定を Claude Desktop の設定ファイルに追加します。

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ES_URL",
        "-e", "ES_API_KEY",
        "docker.elastic.co/mcp/elasticsearch",
        "stdio"
      ],
      "env": {
        "ES_URL": "<elasticsearch-cluster-url>",
        "ES_API_KEY": "<elasticsearch-API-key>"
      }
    }
  }
}

<elasticsearch-cluster-url> を Elasticsearch クラスターの URL に、<elasticsearch-API-key> を API キーに置き換えてください。

streamable-HTTP プロトコルを設定する

ウェブベースの統合を行う場合、または複数の同時接続クライアントをサポートする必要がある場合は、streamable-HTTP プロトコルを使用してください。

HTTP モード用の環境変数を設定する

stdio プロトコルと同じ環境変数を設定します。

• ES_URL：Elasticsearch クラスターの URL
• 認証には、次のいずれかのオプションを使用します。
  • API キー：ES_API_KEY に Elasticsearch API キーを設定します
  • Basic 認証：ES_USERNAME と ES_PASSWORD に Elasticsearch の認証情報を設定します
• （任意）ES_SSL_SKIP_VERIFY：SSL/TLS 証明書の検証をスキップするには、true に設定します

HTTP モードでコンテナを実行する

HTTP モードで MCP サーバーを起動します。

docker run --rm \
  -e ES_URL \
  -e ES_API_KEY \
  -p 8080:8080 \
  docker.elastic.co/mcp/elasticsearch \
  http

ストリーミング可能な HTTP エンドポイントは http://<host>:8080/mcp で利用できます。ヘルスチェックエンドポイントは http://<host>:8080/ping で利用できます。

HTTP プロキシを使用して Claude Desktop を設定する

stdio プロトコルのみをサポートする Claude Desktop（無料版）を使用している場合は、mcp-proxy を使って stdio とストリーミング可能な HTTP をブリッジします。

1. mcp-proxy をインストールします。

   uv tool install mcp-proxy
   

   別のインストール方法については、mcp-proxy/README.md を参照してください。

2. 次の設定を Claude Desktop に追加します。

   {
     "mcpServers": {
       "elasticsearch-mcp-server": {
         "command": "/<home-directory>/.local/bin/mcp-proxy",
         "args": [
           "--transport=streamablehttp",
           "--header", "Authorization", "ApiKey <elasticsearch-API-key>",
           "http://<mcp-server-host>:<mcp-server-port>/mcp"
         ]
       }
     }
   }
   

   <home-directory>、<elasticsearch-API-key>、<mcp-server-host>、<mcp-server-port> をそれぞれの値に置き換えます。

接続を確認する

MCP クライアントを設定したら、接続が機能することを確認します。

1. MCP クライアント（Claude Desktop や Cursor など）を起動します。
2. 利用可能な MCP サーバーの一覧に Elasticsearch MCP Server が表示されることを確認します。
3. エージェントのインターフェイスから簡単なクエリを試し、Elasticsearch のインデックスにアクセスできることを確認します。

接続に失敗する場合は、次の点を確認してください。

• Elasticsearch クラスターの URL が正しく、AWS 環境からアクセスできること
• 認証情報が有効で、必要な権限があること
• コンテナと Elasticsearch クラスター間のネットワーク接続が確立されていること（セキュリティグループとネットワーク ACL を確認してください）
• Docker が実行中で、コンテナが正常に起動していること（docker logs <container-id> でコンテナログを確認してください）

ヘルスとステータスを監視する

次の方法で Elasticsearch MCP Server のヘルスと正常な動作を監視します。

コンテナのステータスを確認する

コンテナが実行中であることを確認します。

docker ps | grep elasticsearch-mcp-server

コンテナが Up ステータスで一覧に表示されるはずです。

ヘルスエンドポイントをテストする（HTTP モード）

ストリーミング可能な HTTP プロトコルを使用している場合は、ヘルスチェックエンドポイントをテストします。

curl http://<host>:8080/ping

成功すると pong が返され、サーバーが実行中で正常であることを示します。

コンテナログを確認する

問題を特定するには、コンテナログを確認します。

docker logs <container-id>

次の項目に関連するエラーメッセージを確認してください。

• Elasticsearch への接続失敗
• 認証エラー
• ネットワーク接続の問題

Elasticsearch への接続を確認する

コンテナから Elasticsearch クラスターへの接続をテストします。

docker exec <container-id> curl -k -u <username>:<password> <ES_URL>

または、API キーを使用します。

docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>

成功すると、コンテナから Elasticsearch クラスターに接続できることを示します。

セキュリティと機密情報

Elasticsearch MCP Server は認証情報を安全に取り扱います。

認証情報の保存

• API キーとパスワード：コンテナに渡される環境変数にのみ保存されます。ディスクへの永続化やログへの記録は行われません。
• 環境変数：コンテナの実行時に設定します。本番環境で認証情報を安全に管理するには、AWS Secrets Manager または AWS Systems Manager Parameter Store を使用してください。

データの暗号化

• 転送中：ES_URL に https:// プロトコルを使用すると、MCP サーバーは HTTPS 経由で Elasticsearch と通信します。Elasticsearch クラスターで SSL/TLS が有効になっていることを確認してください。
• 保存時：コンテナはデータをローカルに保存しません。すべてのデータは Elasticsearch クラスター内に保持され、クラスターの暗号化設定が適用されます。

ベストプラクティス

• API キーは定期的にローテーションしてください（本番環境では 30～90 日ごと）。
• 必要最小限の権限を持つ API キーを使用してください（可能であれば、特定のインデックスに対する読み取り専用アクセス）。
• 認証情報をバージョン管理にコミットしたり、ログで共有したりしないでください。
• 認証情報をハードコーディングするのではなく、AWS Secrets Manager または Parameter Store を使用して実行時に注入してください。

AWS サービスクォータ

Elasticsearch MCP Server は、AWS 環境内でコンテナとして実行されます。次の AWS サービスクォータを考慮してください。

• EC2 インスタンスの制限：EC2 で実行する場合は、インスタンスタイプが想定されるワークロードに対応していることを確認してください。
• Elastic Container Service (ECS)：ECS を使用する場合は、ECS サービスクォータを確認してください。
• Elastic Kubernetes Service (EKS)：EKS を使用する場合は、EKS サービスクォータを確認してください。
• ネットワーク帯域幅：コンテナと Elasticsearch クラスター間のネットワーク帯域幅が十分であることを確認してください。

クォータの引き上げを申請するには、AWS Service Quotas コンソールを使用するか、AWS General Reference Guideを参照してください。

利用可能なツール

接続すると、MCP サーバーはエージェントに次のツールを提供します。

• list_indices：利用可能なすべての Elasticsearch インデックスを一覧表示します
• get_mappings：指定した Elasticsearch インデックスのフィールドマッピングを取得します
• search：クエリ DSL を使用して Elasticsearch 検索を実行します
• esql：ES|QL クエリを実行します
• get_shards：すべてまたは指定したインデックスのシャード情報を取得します

エージェントはこれらのツールを使用して、自然言語での会話を通じて Elasticsearch データを操作できます。

次のステップ

• Elastic プラットフォームで利用できる AI 搭載機能について学ぶ
• Elasticsearch でカスタム AI エージェントを構築するために Agent Builder を活用する