Elasticsearch 7.x MCP Server

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

[!IMPORTANT] このフォークは Elasticsearch 7.x のみを対象としています。@elastic/elasticsearch の 7.17 クライアントを固定しており、 その Product Check は 7.14 より前のサーバーも許可します。Elasticsearch 8.x クラスターの場合は、 このフォークの元になったアップストリームプロジェクト @awesome-ai/elasticsearch-mcp を使用してください — 8.x クライアントは 7.x サーバーと通信できず、その逆も同じです。

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

機能概要

ツールは3つのセットに分かれています。常に公開されるのは最初のセットだけです。残りの2つは環境変数によるオプトインなので、本番環境では削除機能を提供せずに診断機能だけを提供できます。ゲート制御は登録時に行われます。無効なツールは tools/list に一切表示されないため、モデルはそれを呼び出せず、エージェントのコンテキストも消費しません。

常に利用可能 — データの読み取りと書き込み

クラスター

• elasticsearch_health: クラスターのヘルス状態（オプションでインデックスレベルまで）

• cluster_info: クラスター名、Elasticsearch のバージョンとビルドのフレーバー

インデックス操作

• list_indices: インデックスの一覧を Elasticsearch ワイルドカード（log-*）でフィルタリングして表示

• create_index: オプションの設定とマッピングを指定してインデックスを作成

• reindex: インデックスをコピーする（クエリでのフィルタリングやスクリプトでの変換も可能）

• get_aliases: どのエイリアスがどのインデックスを指しているかを確認する

マッピング

• get_mappings: インデックスのフィールドを、型付きのドットパスとして表示し、続けて生のマッピングを表示

• create_mapping: インデックスのマッピングを作成または更新

検索とデータ

• search: クエリ DSL で検索を実行。クエリ自身が highlight を持っていない限り、すべてのテキストフィールド（ネストされたものも含む）にハイライトを注入

• count: ドキュメントを転送せずに、マッチするドキュメント数を返す

• get_document: ID を指定して1件のドキュメントを取得

• bulk: 多数のドキュメントを一度にインデックス登録

テンプレート

• create_index_template: コンポーザブルインデックステンプレートを作成または更新

• get_index_template: インデックステンプレートを読み取る

タスク

• get_task: reindex が返すような長時間実行タスクの進捗状況を確認する

ES_ADMIN_TOOLS=true — 診断（読み取り専用）

これらは読み取り専用なので、本番環境で有効にしても安全です。このセットのポイントはまさにそこにあります。エージェントは、誰かがクラスターにログインしなくても、インデックスが不健全な理由を説明できます。

• explain_allocation: シャードが未割り当ての理由と、各アロケーターの判断結果を表示

• list_shards: シャードレベルの状態を確認。STARTED ではないコピーを先頭に表示

• list_nodes: ノードごとのヒープ、CPU、ロード、ディスク圧力を確認

• get_index_stats: インデックスごとのカウンター — サイズ、セグメント、インデクシング、検索、マージ

• get_index_settings: インデックスの設定（refresh_interval、レプリカ、読み取り専用ブロック）を取得

• get_cluster_settings: 実行時に上書きされたクラスター設定を確認

• list_tasks: クラスターが現在実行中のタスクを確認

ES_ALLOW_DESTRUCTIVE=true — 元に戻せない操作

ステージング環境を想定しており、デフォルトではオフなので、本番環境からは一切到達できません。

• delete_index: インデックスとそのデータを削除

• delete_document: ID を指定して1件のドキュメントを削除

• delete_by_query: クエリにマッチするすべてのドキュメントを削除 — 非同期で、タスク ID を返し、削除はバックグラウンドで続行

• delete_index_template: インデックステンプレートを削除

フラグが有効でも、これらはワイルドカード、カンマ区切りのリスト、*、_all を拒否します。対象は一度に1つの名前付きインデックスだけです。logs-* を単一のインデックスと誤解したモデルは、クラスターを空にする代わりに拒否を受け取ります。

仕組み

1. MCP クライアントがリクエストを分析し、必要な Elasticsearch 操作を判断します。

2. MCP サーバーがその操作を実行します（インデックス一覧の取得、マッピングの取得、検索の実行）。

3. MCP クライアントが結果を処理し、ユーザーフレンドリーな形で表示します。

Related MCP server: Elasticsearch 7.x MCP Server

はじめに

前提条件

• Elasticsearch 7.x インスタンス（7.8 で検証済み。7.17 クライアントは 6.8 から 7.x をサポート）

• Elasticsearch の認証情報 — API キー、またはユーザー名とパスワード

• MCP クライアント: Claude Code、Claude Desktop、Codex、Cursor、その他 stdio で MCP を話せるもの

GitHub Packages への認証（一度だけ）

[!IMPORTANT] このパッケージは GitHub Packages に公開されており、npmjs.com ではありません。GitHub Packages は 公開パッケージでもトークンが必要です。トークンを追加するまで、以下のすべてのインストールは 401 で失敗します。 ユーザーレベルの ~/.npmrc に追加してください:

@agrica:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

YOUR_GITHUB_TOKEN は read:packages スコープを持つ personal access token です。

プロジェクトファイルではなく、自分の ~/.npmrc に置いてください — リポジトリにコミットされたトークンは漏洩したトークンです。また、一部のパッケージマネージャーはそこから読み取ることを完全に拒否します。

クライアントに接続する

以降のすべての例では ES_HOST と ES_API_KEY を設定しています。ベーシック認証を使う場合は ES_USERNAME / ES_PASSWORD に置き換え、診断ツールを使うには ES_ADMIN_TOOLS=true を追加し、複数のインスタンスを宣言する場合は ES_INSTANCE_LABEL を設定してください — 設定オプション を参照してください。

claude mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  --env ES_ADMIN_TOOLS=true \
  -- npx -y @agrica/elasticsearch7-mcp

セッション内で /mcp を実行すると、サーバーとそのツールが一覧表示されます。

間違いやすい点が2つあります:

• -- の後ろはすべてサーバーを実行するコマンドです。これがないと Claude Code は -y を自分自身のフラグとして解析しようとします。

• サーバー名を --env の直後に置かないでください。CLI はそれを別の KEY=value ペアとして読み取り、拒否します。上の例ではサーバー名が先頭にあるため、うまく動作します。

サーバーはローカルスコープで追加されるため、現在のプロジェクトでのみ読み込まれます。どこでも使えるようにするには --scope user を、チームと共有するために .mcp.json に書き込むには --scope project を追加してください — コミットされた .mcp.json には API キーが含まれることになるので、認証情報は user スコープを推奨します。

claude_desktop_config.json を編集します。設定 > 開発者 > 設定を編集 で開くか、Windows の %APPDATA%\Claude\ または macOS の ~\Library\Application\Support\Claude\ にあります:

{
  "mcpServers": {
    "elasticsearch7": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://your-cluster:9200",
        "ES_API_KEY": "your-api-key",
        "ES_ADMIN_TOOLS": "true"
      }
    }
  }
}

その後、Claude Desktop を再起動します。このファイルは起動時にしか読み込まれません。

codex mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  -- npx -y @agrica/elasticsearch7-mcp

または、~/.codex/config.toml に手動で書き込むこともできます。Codex ではテーブル名がアンダースコア付きの mcp_servers となり、環境変数はインラインではなく独立したサブテーブルに入ることに注意してください。

[mcp_servers.elasticsearch7]
command = "npx"
args = ["-y", "@agrica/elasticsearch7-mcp"]

[mcp_servers.elasticsearch7.env]
ES_HOST = "https://your-cluster:9200"
ES_API_KEY = "your-api-key"
ES_ADMIN_TOOLS = "true"

Codex 内で /mcp と入力すると、サーバーが読み込まれていることを確認できます。

このサーバーは通常の stdio MCP サーバーなので、MCP クライアント一覧 にあるどのクライアントでも動作します。必要なものは3つです: コマンド npx、引数 -y @agrica/elasticsearch7-mcp、そして環境変数の ES_* 群です。ポートで待ち受けることはなく、stdout には MCP プロトコル以外を書きません — 診断情報は stderr に送られます。

設定オプション

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

[!NOTE] API キーか、ユーザー名とパスワードの両方のどちらかを指定する必要があります。

[!WARNING] ES_ADMIN_TOOLS と ES_ALLOW_DESTRUCTIVE には、上記の接続変数とは異なり、接頭辞のないレガシーエイリアスがありません。これは意図的なものです。裸の ADMIN_TOOLS や ALLOW_DESTRUCTIVE が環境変数にあると、deletion がどの環境からも到達できるかどうかを決めるものを、誤って設定してしまいがちです。

どちらも true または 1 を受け付けます。それ以外は、環境変数が未設定も含み、オフとして扱まれます。

結果サイズ

ツールの結果は 32 KB（ES_MAX_RESULT_BYTES）に上限が設定されています。特にログ集約クラスターでは重要です。上限がない場合、1年間の日次インデックスを対象にした list_shards を1回呼び出すと、1つの応答で 385 KB — 約 96,000 トークン — が返り、ほとんどのセッションが保持しきれない容量になります。

結果が切り詰められると、その旨が表示され、どれだけ切り捨てられたか、どのような小さな質問をすれば良いかが示されます。3つのツールはこれに合わせて応答を整形します。

• list_indices と list_shards は読み取り可能なサマリーを返し、それと同じ行がテキストとして verbose に含まれます。

• search は1回の呼び出しで size を 100 に制限し、ページングするための from ををします。

• get_mappings は最初にフィールドを次に生のマッピングを return するため、フィールドが多数あっても質問に答えられます。

list_indices、list_shards、get_index_settings、get_mappings の4つは、読み取り可能な応答に加えて、型付けられた構造化出力でも答えを返します。クライアントはテキストを解析せずに表の行を読むことができます。これは、読みやすく応答が残した余りから作られるため、部分的な一覧が数値として確認できます。returned と total が表示されます。

pnpm run measure をビルドした出力に対して実行すると、現在の数値を自分の設定で確認できます。

複数のインスタンスのラベル付け

ほとんどの構成では、このサーバーを複数回宣言します — クラスターごとに1エントリです。エントリはそれ以外は同一なので、クライアントには同じ名前のサーバーが並び、区別できません。 ES_INSTANCE_LABEL はサーバーの表示タイトルになります。エントリがどの環境に向いているかを示すのに最適です。

{
  "mcpServers": {
    "es7-prod": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-prod:9200",
        "ES_API_KEY": "prod-key",
        "ES_INSTANCE_LABEL": "production",
        "ES_ADMIN_TOOLS": "true"
      }
    },
    "es7-staging": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-staging:9200",
        "ES_API_KEY": "staging-key",
        "ES_INSTANCE_LABEL": "staging",
        "ES_ADMIN_TOOLS": "true",
        "ES_ALLOW_DESTRUCTIVE": "true"
      }
    }
  }
}

That pair is the intended shape: diagnostics on both, but only removes is staging. Production keeps the tools that explain an unhealthy index, and never exposes a mechanism by which data could be removed — the model cannot call what never got registered.

The label is also printed to stderr at startup, which is what to look at when a client reports a connection but you can't tell which cluster answered.

複数の URL 設定

高可用性とロードバランシングのために、複数の Elasticsearch ノードを設定できます:

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

設定されたノード間で、クライアントが自動的にフェイルオーバーとロードバランスを処理してくれます。

Docker で実行する

各リリースは、マルチアーカイブ イメージ (linux/amd64, linux/arm64) を GitHub Container Registry に公開しています:

docker pull ghcr.io/agrica/elasticsearch7-mcp:latest

サーバーは stdio で通信するので、コンテナにはインタラクティブな標準入力が必要で、公開ポートは必要ありません。MCP クライアントの中では:

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ES_HOST",
        "-e", "ES_API_KEY",
        "ghcr.io/agrica/elasticsearch7-mcp:latest"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

[!NOTE] npm パッケージと同様、このイメージも GitHub Packages にあります。リポジトリは公開されていますが、 取得するには read:packages スコープが付いたトークンが必要です。

イメージには公開ポートもボリュームも不要です。stdio で通信するので、標準入出力は MCP クライアントのものになります。

クエリ例

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

クラスタ管理

• "私の Elasticsearch クラスタのヘルス状態はどうなっていますか?"

• "頂点にあるクラスタには、有効なノードがいくつありますか?"

インデックス操作

• "私の Elasticsearch クラスタには、どのインデックスがありますか?"

• "‘users’ という新しいインデックスを、シャード3つ・レプリカ1つの構成で作成して。"

• "‘old_index’ から ‘new_index’ にデータを再インデックスして。"

マッピング管理

• "‘products’ インデックスのフィールドマッピングを表示して。"

• "‘products’ インデックスに、‘tags’ という keyword タイプのフィールドを追加して。"

検索 & データ操作

• "先月の 500 ドルを超える注文をすべて検索して。"

• "どの製品がもっとも星5つのレビューを取得されましたか?"

• "この顧客レコードを、’customers’ インデックスに一括インポートして。"

テンプレート管理

• "‘logs-*’ というパターンのログ用インデックステンプレートを作成して。"

• "持っているインデックステンプレートをすべて表示して。"

診断 (ES_ADMIN_TOOLS=true が必要)

• "‘logs-2026’ インデックスが黄色です。なぜシャードが未割当てなのですか?"

• "ディスクのウォーターマークに近いノードはありますか?"

• "自分のインデックスの中でどれが最も大きく、そのうちどのくらいが削除済みドキュメントですか?"

• "このクラスタで誰かがシャードの割当を無効にしたログがありますか?"

• "再インデックスがまだ実行中ですか?"

破壊的操作 (ES_ALLOW_DESTRUCTIVE=true が必要)

• "‘smoke-test-source’ インデックスを削除して。"

• "‘logs-archive’ から 2024 年より前のドキュメントを全部削除して。"

トラブルシューティング

バグを見つけたか、足りないツールありますか? GitHub リポジトリで issue を開いてください。コードを扱う場合は、CONTRIBUTING.md から始めてください。