Elasticsearch/OpenSearch MCP Server

Elasticsearch/OpenSearch MCP サーバー

概要

Elasticsearch と OpenSearch を操作する Model Context Protocol（MCP）サーバーの実装です。このサーバーは、一連のツールを通じてドキュメントの検索、インデックスの分析、クラスターの管理を可能にします。

デモ

https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15

機能

一般的な操作

• general_api_request：一般的な HTTP API リクエストを実行します。専用のツールがない Elasticsearch/OpenSearch API を使用する場合に利用します。

インデックス操作

• list_indices：すべてのインデックスを一覧表示します。
• get_index：1 つ以上のインデックスに関する情報（マッピング、設定、エイリアス）を返します。
• create_index：新しいインデックスを作成します。
• delete_index：インデックスを削除します。
• create_data_stream：新しいデータストリームを作成します（一致するインデックステンプレートが必要です）。
• get_data_stream：1 つ以上のデータストリームに関する情報を取得します。
• delete_data_stream：1 つ以上のデータストリームと、そのバックインデックスを削除します。

ドキュメント操作

• search_documents：ドキュメントを検索します。
• index_document：インデックス内のドキュメントを作成または更新します。
• get_document：ID でドキュメントを取得します。
• delete_document：ID でドキュメントを削除します。
• delete_by_query：指定したクエリに一致するドキュメントを削除します。

クラスター操作

• get_cluster_health：クラスターの健全性に関する基本情報を返します。
• get_cluster_stats：クラスター統計の概要を返します。

エイリアス操作

• list_aliases：すべてのエイリアスを一覧表示します。
• get_alias：特定のインデックスのエイリアス情報を取得します。
• put_alias：特定のインデックスのエイリアスを作成または更新します。
• delete_alias：特定のインデックスのエイリアスを削除します。

アナライザー操作

• analyze_text：指定したアナライザーまたはカスタム分析チェーンを使ってテキストを分析します。検索クエリのデバッグやテキストがどのようにトークン化されるかの理解に役立ちます。

環境変数の設定

MCP サーバーは、次の環境変数をサポートしています。

基本認証（ユーザー名／パスワード）

• ELASTICSEARCH_USERNAME：基本認証用のユーザー名
• ELASTICSEARCH_PASSWORD：基本認証用のパスワード
• OPENSEARCH_USERNAME：OpenSearch の基本認証用ユーザー名
• OPENSEARCH_PASSWORD：OpenSearch の基本認証用パスワード

API キー認証（Elasticsearch のみ）- 推奨

• ELASTICSEARCH_API_KEY：Elasticsearch または Elastic Cloud の認証に使用する API キー。

接続設定

• ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS：ホストのカンマ区切りリスト（デフォルト：https://localhost:9200）
• ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS：名前付きクラスター設定を指定するインライン JSON オブジェクト。設定すると、ツール呼び出しで省略可能な cluster パラメーターを使って、特定のクラスターを指定できます。
• ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE：クラスターオブジェクトを含む JSON ファイルのパス。設定が別の JSON ファイル（例：MCP クライアント設定）内に埋め込まれている場合に推奨されます。JSON 内の JSON のエスケープが不要になります。両方が設定されている場合は、インライン変数より優先されます。
• DEFAULT_CLUSTER：マルチクラスター設定時に、ツール呼び出しで cluster が省略された場合に使用するデフォルトのクラスター名（デフォルトは、設定されている最初のクラスター）
• VERIFY_CERTS：SSL 証明書を検証するかどうか（デフォルト：false）
• REQUEST_TIMEOUT：リクエストのタイムアウト時間（秒）（任意。設定されていない場合はクライアントのデフォルト値を使用）

複数クラスターの設定

デフォルトでは、サーバーは ELASTICSEARCH_HOSTS、ELASTICSEARCH_USERNAME、ELASTICSEARCH_PASSWORD、ELASTICSEARCH_API_KEY で指定された単一の Elasticsearch クラスター、または OPENSEARCH_HOSTS、OPENSEARCH_USERNAME、OPENSEARCH_PASSWORD で指定された単一の OpenSearch クラスターを使用します。複数の名前付きクラスターを設定するには、MCP サーバーの設定内で ELASTICSEARCH_CLUSTERS（または OPENSEARCH_CLUSTERS）に JSON オブジェクトを設定します。値は別の JSON ファイルに埋め込まれた JSON 文字列であるため、内側の引用符をエスケープする必要があります。

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_CLUSTERS": "{\"prod\": {\"hosts\": [\"https://prod-es:9200\"], \"api_key\": \"<PROD_API_KEY>\", \"verify_certs\": true}, \"staging\": {\"hosts\": [\"https://staging-es:9200\"], \"username\": \"elastic\", \"password\": \"<STAGING_PASSWORD>\"}}",
        "DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

読みやすくするには、ELASTICSEARCH_CLUSTERS_FILE（または OPENSEARCH_CLUSTERS_FILE）で単独の JSON ファイルを指定してください。値はパスだけなので、JSON 内の JSON のエスケープが不要になります。

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_CLUSTERS_FILE": "/etc/mcp/es-clusters.json",
        "DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

/etc/mcp/es-clusters.json：

{
  "prod": {
    "hosts": ["https://prod-es:9200"],
    "api_key": "<PROD_API_KEY>",
    "verify_certs": true
  },
  "staging": {
    "hosts": ["https://staging-es:9200"],
    "username": "elastic",
    "password": "<STAGING_PASSWORD>"
  }
}

すべてのツールは、省略可能な cluster パラメーターを受け付けます。省略した場合、サーバーは DEFAULT_CLUSTER を使用します。DEFAULT_CLUSTER が設定されていない場合は、JSON オブジェクト内の最初のクラスターがデフォルトとして使用されます。特定のクラスターを対象にするツール呼び出しは、次のようになります。

{
  "cluster": "staging",
  "index": "logs-*",
  "body": {
    "query": {
      "match_all": {}
    }
  }
}

MCP サーバーの認証（HTTP トランスポートのみ）

HTTP ベースのトランスポート（SSE または Streamable HTTP）で MCP サーバーを実行する場合、Bearer トークン認証を有効にして、権限のないアクセスからサーバーを保護できます。

• MCP_API_KEY：MCP サーバー認証用の API キー。クライアントは Authorization: Bearer <MCP_API_KEY> ヘッダーを含める必要があります。

重要なセキュリティ上の注意：

• 認証が適用されるのは、HTTP トランスポート（sse、streamable-http）のみです。stdio トランスポートはローカルのプロセス通信を使用するため、認証は不要です。
• MCP_API_KEY が設定されていない場合、MCP サーバーには認証なしでアクセスできます。サーバーをネットワーク経由で公開する場合、これはセキュリティリスクになります。
• HTTP トランスポートを使って本番環境にデプロイする場合は、必ず MCP_API_KEY を設定してください。

# Generate a secure API key (example using openssl)
export MCP_API_KEY=$(openssl rand -base64 32)

# Or set a custom API key
export MCP_API_KEY="your-secure-api-key-here"

高リスク操作の無効化

• DISABLE_HIGH_RISK_OPERATIONS：true に設定すると、すべての書き込み操作を無効にします（デフォルト：false）
• DISABLE_OPERATIONS：無効にする特定の操作のカンマ区切りリスト（任意。設定されていない場合は、デフォルトの書き込み操作リストを使用）

DISABLE_HIGH_RISK_OPERATIONS が true に設定されている場合、書き込み操作を実行するすべての MCP ツールは MCP クライアントから完全に非表示になります。このモードでは、次の MCP ツールがデフォルトで無効になります。

• インデックス操作：

  • create_index
  • delete_index

• ドキュメント操作：

  • index_document
  • delete_document
  • delete_by_query

• データストリーム操作：

  • create_data_stream
  • delete_data_stream

• エイリアス操作：

  • put_alias
  • delete_alias

• 一般的な API 操作：

  • general_api_request

必要に応じて、DISABLE_OPERATIONS 環境変数に、無効にする操作をカンマ区切りで指定できます。

# Disable High-Risk Operations
export DISABLE_HIGH_RISK_OPERATIONS=true
# Disable specific operations only
export DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"

GCF レスポンスエンコーディング（任意）

ツール結果のペイロードを、トークン最適化されたワイヤーフォーマットであるGCF（Graph Compact Format）としてシリアライズし、モデルが読み取るコンテンツブロックに含めることができます。Elasticsearch は大規模で均一なレコードセット（検索ヒット、集約バケット、マッピング）を返しますが、これらは GCF が最も効率よく圧縮できる形式です。代表的なレスポンスでは、情報を損なうことなく、コンパクト JSON より約 39％少ないトークン数（検索ヒットでは 40％）になります。

export RESPONSE_FORMAT=gcf

structuredContent は変更されずに保持されるため、ツールで宣言された出力スキーマは引き続き検証され、モデル以外のクライアントには引き続き JSON が返されます。再エンコードされるのは、モデル向けのテキストブロックのみです。エンコーディングはフェイルセーフです。GCF が暗黙の近似をせずに拒否する、GCF の正規の int64 数値範囲外の値を含むあらゆるエラーが発生した場合、元の JSON 結果がそのまま保持されるため、エンコーディングを理由にツール呼び出しが破棄されることはありません。RESPONSE_FORMAT が未設定の場合、デフォルトの動作は変わりません。

トークン数の比較を再現するには、uv run --with tiktoken python benchmarks/gcf_benchmark.py を実行してください。

Elasticsearch/OpenSearch クラスターを起動する

Docker Compose を使用して Elasticsearch/OpenSearch クラスターを起動します。

# For Elasticsearch
docker-compose -f docker-compose-elasticsearch.yml up -d

# For OpenSearch
docker-compose -f docker-compose-opensearch.yml up -d

Elasticsearch のデフォルトのユーザー名は elastic、パスワードは test123 です。OpenSearch のデフォルトのユーザー名は admin、パスワードは admin です。

http://localhost:5601 から Kibana/OpenSearch Dashboards にアクセスできます。

Stdio

オプション 1：uvx を使用する

uvx を使用すると、PyPI からパッケージが自動的にインストールされるため、リポジトリをローカルにクローンする必要はありません。の設定ファイル claude_desktop_config.json に以下の設定を追加してください。

// For Elasticsearch with username/password
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// For Elasticsearch with API key
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
      }
    }
  }
}

// For OpenSearch
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": [
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

オプション 2：ローカル開発で uv を使用する

uv を使用するには、リポジトリをローカルにクローンし、ソースコードへのパスを指定する必要があります。Claude Desktop の設定ファイル claude_desktop_config.json に以下の設定を追加してください。

// For Elasticsearch with username/password
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// For Elasticsearch with API key
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
      }
    }
  }
}

// For OpenSearch
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

SSE

オプション 1：uvx を使用する

# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uvx elasticsearch-mcp-server --transport sse

# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

オプション 2：uv を使用する

# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uv run src/server.py elasticsearch-mcp-server --transport sse

# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Streamable HTTP

オプション 1：uvx を使用する

# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uvx elasticsearch-mcp-server --transport streamable-http

# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

オプション 2：uv を使用する

# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uv run src/server.py elasticsearch-mcp-server --transport streamable-http

# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

互換性

MCP サーバーは Elasticsearch 7.x、8.x、9.x と互換性があります。デフォルトでは、Elasticsearch 8.x クライアント（サフィックスなし）を使用します。

MCP サーバー	Elasticsearch
elasticsearch-mcp-server-es7	Elasticsearch 7.x
elasticsearch-mcp-server	Elasticsearch 8.x
elasticsearch-mcp-server-es9	Elasticsearch 9.x
opensearch-mcp-server	OpenSearch 1.x、2.x、3.x

Elasticsearch 7.x クライアントを使用するには、elasticsearch-mcp-server-es7 バリアントを実行してください。Elasticsearch 9.x の場合は、elasticsearch-mcp-server-es9 を使用してください。例：

uvx elasticsearch-mcp-server-es7

異なる Elasticsearch バリアント（例：7.x または 9.x）をローカルで実行する場合は、pyproject.toml の elasticsearch 依存関係のバージョンを更新してから、次のコマンドでサーバーを起動してください。

uv run src/server.py elasticsearch-mcp-server

Kubernetes へのデプロイ

Docker イメージは ghcr.io/cr7258/elasticsearch-mcp-server に公開されており、Helm チャートはリポジトリ oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server の OCI アーティファクトとして利用できます。

インストール手順、設定リファレンス、使用例については、Helm チャートの README をご覧ください。

ライセンス

このプロジェクトは Apache License Version 2.0 の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。