Elasticsearch MCP Server
Elasticsearch/OpenSearch MCP サーバー
概要
Elasticsearch および OpenSearch との対話を提供する Model Context Protocol (MCP) サーバーの実装です。このサーバーは、一連のツールを通じてドキュメントの検索、インデックスの分析、クラスターの管理を可能にします。
Related MCP server: Elasticsearch MCP Server
デモ
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 サーバー設定内の JSON オブジェクトに ELASTICSEARCH_CLUSTERS(または OPENSEARCH_CLUSTERS)を設定します。値は別の 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 トランスポートのみ)
MCP サーバーを HTTP ベースのトランスポート(SSE または Streamable HTTP)で実行する場合、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_indexdelete_index
ドキュメント操作:
index_documentdelete_documentdelete_by_query
データストリーム操作:
create_data_streamdelete_data_stream
エイリアス操作:
put_aliasdelete_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)としてシリアライズすることを選択できます。GCF はトークン最適化されたワイヤーフォーマットです。Elasticsearch は大規模で均一なレコードセット(検索ヒット、集計バケット、マッピング)を返しますが、これは GCF が最も効率的に圧縮する形状です。代表的なレスポンスでは、コンパクトな JSON よりも約 39% 少ないトークン(検索ヒットでは 40%)で、ロスレスです。
export RESPONSE_FORMAT=gcfstructuredContent は変更されずに保持されるため、ツールの宣言された出力スキーマは引き続き検証され、モデル以外のクライアントは引き続き JSON を受け取ります。モデル向けのテキストブロックのみが再エンコードされます。エンコーディングはフェイルセーフです。GCF の正規の int64 数値ドメイン外の値(GCF は黙って近似するのではなく拒否します)を含むエラーが発生した場合も、元の 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 です。
Kibana/OpenSearch Dashboards には http://localhost:5601 からアクセスできます。
Stdio
オプション 1: uvx を使用
uvx を使用すると、PyPI からパッケージが自動的にインストールされるため、リポジトリをローカルにクローンする必要はありません。以下の設定を Claude Desktop の設定ファイル 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 /sseStreamable 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-serverKubernetes デプロイメント
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 ファイルを参照してください。
Available Tools
20 toolsanalyze_textB
Analyze text to see how it would be tokenized.
Use this tool to understand how Elasticsearch/OpenSearch tokenizes and transforms text using analyzers. This is essential for debugging search queries and understanding why certain documents match or don't match.
Inputs: text (required), index, filter, cluster, +5 more. Returns: object
create_data_streamB
Create a new data stream.
This creates a new data stream with the specified name. The data stream must have a matching index template before creation.
Inputs: name (required), cluster. Returns: object
create_indexC
Create a new index.
Inputs: index (required), body, cluster. Returns: object
delete_aliasC
Delete an alias for a specific index.
Inputs: name (required), index (required), cluster. Returns: object
delete_by_queryC
Deletes documents matching the provided query.
Inputs: body (required), index (required), cluster. Returns: object
delete_data_streamA
Delete one or more data streams.
Permanently deletes the specified data streams and all their backing indices.
Inputs: name (required), cluster. Returns: object
delete_documentC
Delete a document by ID.
Inputs: id (required), index (required), cluster. Returns: object
delete_indexC
Delete an index.
Inputs: index (required), cluster. Returns: object
general_api_requestA
Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.
Inputs: path (required), method (required), body, params, +1 more.
get_aliasC
Get alias information for a specific index.
Inputs: index (required), cluster. Returns: object
get_cluster_healthC
Returns basic information about the health of the cluster.
Inputs: cluster. Returns: object
get_cluster_statsB
Returns high-level overview of cluster statistics.
Inputs: cluster. Returns: object
get_data_streamC
Get information about one or more data streams.
Retrieves configuration, mappings, settings, and other information about the specified data streams.
Inputs: name, cluster. Returns: object
get_documentC
Get a document by ID.
Inputs: id (required), index (required), cluster. Returns: object
get_indexB
Returns information (mappings, settings, aliases) about one or more indices.
Inputs: index (required), cluster. Returns: object
index_documentC
Creates or updates a document in the index.
Inputs: index (required), document (required), id, cluster. Returns: object
list_aliasesB
List all aliases.
Inputs: cluster. Returns: result
list_indicesC
List all indices.
Inputs: cluster. Returns: result
put_aliasC
Create or update an alias for a specific index.
Inputs: body (required), name (required), index (required), cluster. Returns: object
search_documentsC
Search for documents.
Inputs: body (required), index (required), cluster. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a clearly distinct resource and action (index, document, alias, data stream, cluster, analysis, or generic API). Overlaps like get_index vs list_indices and get_alias vs list_aliases are cleanly separated by specificity. The general_api_request fallback is explicitly scoped to APIs without dedicated tools, so it does not create real misselection risk.
Tools follow a consistent snake_case verb_noun convention (create_index, delete_document, get_cluster_health, put_alias, etc.). The only minor exception is general_api_request, but it still fits the overall readable naming style. There is no mixing of camelCase or conflicting verb patterns.
At 20 tools, the surface is slightly heavy by the usual 3–15 guideline, but Elasticsearch is a broad domain and each tool covers a meaningful resource area. The set avoids extreme bloat and does not include redundant operations.
Core CRUD and lifecycle coverage exists for indices, documents, aliases, data streams, and cluster inspection, with search and text analysis included. Notable gaps remain—such as dedicated index template management (required for data streams), bulk operations, and update-by-query—but the general_api_request tool provides a workaround for any missing API.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with Elasticsearch clusters, allowing them to manage indices and execute search queries using natural language.2-
- AlicenseBqualityDmaintenanceConnects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.4Apache 2.0
- FlicenseBqualityDmaintenanceConnects to Elasticsearch clusters through the Model Context Protocol, enabling natural language querying and management of Elasticsearch data. Provides tools to search indices, list available indices, and retrieve index mappings.3-
- AlicenseBqualityDmaintenanceEnables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.1017 npmMIT