Elasticsearch

Elasticsearch MCP サーバー

セキュリティと脅威分析に特化した、強化版 Elasticsearch MCP サーバーソリューション

これは、TocharianOU が保守する、セキュリティに特化したプロフェッショナル向けソリューションです。すべての Elasticsearch API を包括的に利用でき、特にセキュリティ分析、脅威検出、インシデント調査に最適化されています。高度なセキュリティ監視、異常検知、脅威ハンティング、根本原因分析、包括的な監査機能を備えています。

主なセキュリティ機能：

• リアルタイムの脅威検出とセキュリティ監視
• 高度な機械学習による異常検知
• 根本原因分析と攻撃チェーンの追跡
• セキュリティインシデントの調査とフォレンジック
• コンプライアンス監視と監査レポート作成

---

**注：**このソリューションは、セキュリティの専門家、SOC チーム、脅威アナリスト向けに設計されています。

Model Context Protocol（MCP）を使用して、MCP クライアント（Claude Desktop など）から Elasticsearch のデータに直接接続できます。自然言語でクエリを実行し、Elasticsearch のセキュリティデータを活用して、高度な脅威分析とインシデント対応を行えます。

前提条件

• Elasticsearch インスタンス
• Elasticsearch の認証情報（API キーまたはユーザー名／パスワード）
• MCP クライアント（例：Claude Desktop）またはリモートアクセス用の HTTP クライアント

複数バージョンの Elasticsearch をサポート

Elasticsearch 5.x～9.x を自動的にサポートし、バージョンをインテリジェントに検出します：

バージョン	ステータス	クライアント	備考
ES 5.x	✅	5.6.22	EOL - 基本ツールのみ
ES 6.x	✅	6.8.8	EOL - ILM を利用可能（6.6 以降）
ES 7.x	✅	7.17.14	LTS - すべての機能を利用可能
ES 8.x	✅	8.19.1	推奨 - 最新機能、ES|QL（8.11 以降）
ES 9.x+	✅	自動フォールバック	将来にも対応

主な機能：

• バージョンの自動検出 - 手動設定は不要です
• スマートなクライアント選択 - ES のバージョンに適したクライアントを読み込みます
• 機能の適応 - サポートされていないツールを無効化します（例：ES 7.9 未満では Data Streams、ES 8.11 未満では ES|QL）
• バージョン固有の最適化 - API の違いを透過的に処理します

動作：

Connect → Detect ES version → Load matching client → Register compatible tools

クエリハーネス（v0.9.0）

v0.9.0 以降、このサーバーにはクエリハーネスが付属します。これは AI モデルとクラスターの間にある決定論的なレイヤーです。設計思想はシンプルです。

モデルが導き、ハーネスが把握します。 意図（「ユーザーごとにログイン失敗を検索する」）はモデルが担います。 正確性（実際のフィールド名、集計可能かどうか、バージョン固有の差異）はハーネスが担います。

原則のレベルで、内部の仕組みには立ち入らずに説明すると、実際には次のようになります。

• 実環境の情報が、同梱された知識より優先され、同梱された知識はモデルの記憶より優先されます。 各クエリは実行前に、クラスターが実際に備えるフィールド機能に照らして検証されます。同梱された ECS（Elastic Common Schema）の語彙は意味を提供し、実際のクラスターは存在するかどうかを提供します。モデル自身の記憶は決して信頼されません。
• 曖昧さのない誤りは通知せずに修正し、曖昧な誤りは案内に変えます。 典型的な例として、最新の ECS マッピングに対する誤った .keyword サフィックスは自動修正され（修正内容は報告されます）、未知のフィールドがある場合は失敗するクエリを阻止し、プロバイダーエラーの代わりに最も近い実在フィールドを返します。
• フィールドの知識はコンテキストウィンドウに持ち込みません。 数千のフィールドを含む ECS ディクショナリー全体は、プロセスメモリー内に保存されます。モデルは必要な少数のフィールドだけを、必要に応じて lookup_fields 経由で取得します。
• すべての失敗は、対処可能でなければなりません。 Elasticsearch の生のエラーは、実際の候補とインデックス名に関するアドバイス（データストリームと従来の Beats の命名規則の違いや、Kibana API 経由でアクセスすべき内部インデックスなど）を含む形に書き換えられます。
• モデルがバージョンに関する知識を持つ必要はありません。 命名規則の変遷、API の違い、マッピング形式の違い（従来の text と .keyword サブフィールドの組み合わせと、最新の単独の keyword）はすべてハーネスが吸収します。同じモデルが ES 5.6 と ES 9.x に対して同じように動作します。9 つの重要なリリースを網羅するバージョンテストマトリックス（5.6 → 9.0）で検証済みです。
• いつでも回避手段を利用できます。 モデルがより適切に判断できる場合（たとえば、クエリの外部で定義されたランタイムフィールドがある場合）は、呼び出しごとに検証をスキップできます（skip_lint）。ハーネスは支援しますが、制約を課すことはありません。

SSL/TLS 接続

自己署名証明書を使って Elasticsearch に接続する場合や、テスト環境で接続する場合は、次の環境変数を設定できます。

NODE_TLS_REJECT_UNAUTHORIZED=0

⚠️ これは Node.js の SSL 証明書検証を無効にします。開発環境またはテスト環境でのみ使用してください。本番環境では、必ず信頼できる CA 証明書を使用してください。

インストールとセットアップ

サーバーをインストール（または実行）し、環境変数でクラスターを指定して、MCP クライアントに登録します。その後、会話を開始するだけで、サーバーが接続し、お使いの ES バージョンがサポートするツールを登録します。

設定オプション

Elasticsearch MCP サーバーでは、次の設定オプションを使用できます。

Elasticsearch の設定

環境変数	説明	必須
ES_URL	Elasticsearch インスタンスの URL	はい
ES_API_KEY	認証用の Elasticsearch API キー	いいえ
ES_USERNAME	基本認証用の Elasticsearch ユーザー名	いいえ
ES_PASSWORD	基本認証用の Elasticsearch パスワード	いいえ
ES_CA_CERT	Elasticsearch SSL/TLS 用のカスタム CA 証明書のパス	いいえ
NODE_TLS_REJECT_UNAUTHORIZED	SSL 証明書の検証を無効にするには 0 を設定します	いいえ

トランスポートモードの設定（v0.3.0 の新機能）

環境変数	説明	デフォルト	値
MCP_TRANSPORT	トランスポートモードの選択	stdio	stdio、http
MCP_HTTP_PORT	HTTP サーバーのポート（HTTP トランスポート使用時）	3000	1-65535
MCP_HTTP_HOST	HTTP サーバーのホスト（HTTP トランスポート使用時）	localhost	有効なホスト名

トランスポートモードの詳細：

• Stdio モード（デフォルト）：Claude Desktop とローカル MCP クライアント向けです
• HTTP Streamable モード：リモートアクセス、API 統合、ウェブアプリケーション向けのスタンドアロン HTTP サーバーとして実行します

クイックスタート

オプション 1：NPM によるインストール（推奨）

1. NPM 経由でグローバルにインストール

   npm install -g @tocharianou/elasticsearch-mcp
   

2. 直接実行

   npx @tocharianou/elasticsearch-mcp
   

オプション 2：GitHub リリース（スタンドアロンパッケージ）

1. リリースパッケージをダウンロード

   • GitHub Releases にアクセスします
   • 最新の .tar.gz ファイルとチェックサムファイル（.sha256 および .sha512）をダウンロードします

2. パッケージの整合性を検証

   shasum -a 256 -c elasticsearch-mcp-v*.tar.gz.sha256
   # Should output: elasticsearch-mcp-v*.tar.gz: OK
   

3. 展開して使用

   mkdir elasticsearch-mcp && cd elasticsearch-mcp
   tar -xzf ../elasticsearch-mcp-v*.tar.gz
   
   # Run with your Elasticsearch credentials
   ES_URL=https://localhost:9200 ES_API_KEY=your-key node dist/index.js
   

オプション 3：ソースからインストール

1. リポジトリをクローン

   git clone https://github.com/TocharianOU/elasticsearch-mcp.git
   cd elasticsearch-mcp
   

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

   npm install
   

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

   npm run build
   

4. Claude Desktop App を設定

   • Claude Desktop App を開きます
   • Settings > Developer > MCP Servers に移動します
   • Edit Config をクリックし、次の設定で新しい MCP サーバーを追加します

   NPM によるインストールの場合：

   {
     "mcpServers": {
       "elasticsearch-mcp-server": {
         "command": "npx",
         "args": [
           "@tocharianou/elasticsearch-mcp"
         ],
         "env": {
           "ES_URL": "your-elasticsearch-url",
           "ES_USERNAME": "elastic",
           "ES_PASSWORD": "your_pass",
           "NODE_TLS_REJECT_UNAUTHORIZED": "0"
         }
       }
     }
   }
   

   ソースからインストールした場合：

   {
     "mcpServers": {
       "elasticsearch-mcp-server-local": {
         "command": "node",
         "args": [
           "/path/to/your/elasticsearch-mcp/dist/index.js"
         ],
         "env": {
           "ES_URL": "your-elasticsearch-url",
           "ES_USERNAME": "elastic",
           "ES_PASSWORD": "your_pass",
           "NODE_TLS_REJECT_UNAUTHORIZED": "0"
         }
       }
     }
   }
   

5. MCP Inspector によるデバッグ（任意）

   ES_URL=your-elasticsearch-url ES_USERNAME=elastic ES_PASSWORD=your_pass npm run inspector
   

インストールと統合に関する注意事項

npm install -g が正常に動作しない場合：

• グローバルインストール時の権限エラー（EACCES） — sudo は使わないでください。グローバルインストールを完全に省略し、MCP クライアントに npx @tocharianou/elasticsearch-mcp を実行させるか（npx は必要に応じてダウンロードします）、ユーザーレベルのプレフィックスを設定してください： npm config set prefix ~/.npm-global を実行し、これを PATH に追加します。
• レジストリが遅い、またはブロックされている場合 — インストール時のみミラーを使用します： npm install -g @tocharianou/elasticsearch-mcp --registry=https://registry.npmmirror.com。
• Node のバージョン — Node 18+ が必要です（node --version）。古い Node ではインストール時ではなく、起動時に ESM/fetch エラーが発生します。
• npx の初回起動 — 初回の npx 実行時にパッケージがダウンロードされます。初回接続時に MCP クライアントがタイムアウトする場合は、ターミナルで npx @tocharianou/elasticsearch-mcp を一度実行してキャッシュを準備してから、再接続してください。
• 完全にオフラインのホスト — GitHub リリースの tarball（オプション 2）を使用し、クライアントの接続先を node /path/to/dist/index.js にします。実行時にダウンロードは発生しません。

Claude Desktop — Settings → Developer → MCP Servers → Edit Config に移動し、上記の JSON ブロックを追加します。編集後にアプリを再起動すると、新しい会話のツール一覧にサーバーが表示されます。

Claude Code（CLI） — サーバーをプロジェクト単位またはグローバルに登録します：

claude mcp add elasticsearch \
  -e ES_URL=https://your-es:9200 -e ES_API_KEY=your-key \
  -- npx @tocharianou/elasticsearch-mcp

その他の MCP クライアント／プラットフォーム統合 — HTTP モード（MCP_TRANSPORT=http、下記参照）で実行し、クライアントの接続先を http://host:port/mcp に設定します。コンテナ化されたプラットフォームでは、クラスター接続ごとにサーバーインスタンスを 1 つ用意するこの構成を推奨します。

認証情報の管理 — 環境変数はクライアントの設定ファイルに平文で保存されます。スーパーユーザーの認証情報ではなく、権限を限定した読み取り専用 API キー（下記の Elasticsearch Access Control を参照）を使用してください。

方法 3：HTTP Streamable モード（v0.3.0 で新登場）

サーバーをスタンドアロンの HTTP サービスとして実行し、リモートアクセスや API 統合に利用できます。

# Start HTTP server (default port 3000)
MCP_TRANSPORT=http \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

# Or with custom port and host
MCP_TRANSPORT=http \
MCP_HTTP_PORT=9000 \
MCP_HTTP_HOST=0.0.0.0 \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

HTTP Streamable モードの機能：

• MCP サーバーを http://host:port/mcp エンドポイントで公開します
• ヘルスチェックを http://host:port/health で利用できます
• セッションベースの接続管理に対応しています
• POST（JSON-RPC リクエスト）と GET（SSE ストリーム）の両方に対応しています
• あらゆる HTTP クライアントまたは MCP SDK と互換性があります

MCP 対応クライアント（または HTTP 経由の通常の JSON-RPC）から /mcp エンドポイントに接続できます。初期化を一度行い、以降の tools/list / tools/call リクエストでは返された mcp-session-id ヘッダーを保持してください。稼働状態の確認には /health を使用します。

利用可能なツール

ツール	説明	最小バージョン
list_indices	パターンフィルター、ヘルスフィルター、並べ替え、トークンを考慮した要約を使ってインデックスを一覧表示します	ES 5.x+
get_mappings	フラット／ツリー／raw モード、フィールドフィルタリング、複数インデックスの比較を使ってフィールドマッピングを取得します	ES 5.x+
es_search	自動ハイライトに加え、ハーネスによるフィールド検証／自動修正を備えた、完全な Query DSL 検索です	ES 5.x+
lookup_fields	適切なフィールド名を検索します。ECS の用語とインデックスの実際のフィールドを照合します	ES 5.x+
execute_es_api	任意の ES REST エンドポイントを直接実行します（GET/POST/PUT/DELETE/HEAD）	ES 5.x+
get_shards	ヘルス分析、問題の検出、推奨事項を含むシャード情報です	ES 5.x+
list_data_streams	ILM 情報とバッキングインデックスの詳細を含む、Data Streams の一覧表示と分析を行います	ES 7.9+
esql_query	ハーネスによるフィールド検証と表形式の出力に対応した、パイプベースの ES|QL クエリを実行します	ES 8.11+

クラスターのバージョンでサポートされないツールは、起動時に自動的にスキップされます。 es_search と esql_query では、特殊なケース（クエリの外部で定義されたランタイムフィールドなど）に対して、skip_lint: true を指定してハーネスの検証を回避できます。

ES|QL クエリツール（esql_query）

ES|QL は Elasticsearch の最新のパイプベースのクエリ言語です。複雑な JSON DSL を使わずに分析やデータ探索を行うのに適しています。

クエリの例：

FROM logs-* | WHERE level == "error" | STATS count = COUNT(*) BY service | SORT count DESC | LIMIT 20
FROM metrics-* | WHERE @timestamp > NOW() - 1 hour | STATS avg_cpu = AVG(cpu.usage) BY host.name
FROM auditbeat-* | WHERE event.action == "user_login" AND event.outcome == "failure" | LIMIT 50

パラメーター：

• query — ES|QL 文字列（必須）
• params — ? プレースホルダーを置き換える位置パラメーター（任意）
• include_types — 出力に列の型情報を含めます（任意、デフォルトは false）
• break_token_rule — 大きな結果に対してトークン制限を回避します（任意、デフォルトは false）
• skip_lint — ハーネスによるフィールド検証を回避します（任意、デフォルトは false）

ES 8.11+ のクラスターでのみ自動的に登録されます。

コントリビューション

コミュニティからのコントリビューションを歓迎します！コントリビューション方法の詳細については、コントリビューションガイドラインをご覧ください。

仕組み

1. MCP クライアント（AI モデル）が何を調べるかを判断し、ツールを呼び出します。
2. ハーネスが稼働中のクラスターに対してリクエストを検証します。曖昧さのない内容は修正し、失敗する内容はブロックし、エラーをガイダンスに変換します。
3. 結果はトークン数の上限内に収まるように整理・要約され（ハイライト、テーブル、集計の要約）、長時間の調査でもコンテキスト制限内に収まります。

セキュリティ分析の例

ヒント

MCP クライアントで試せる、セキュリティに焦点を当てたクエリを紹介します。

脅威の検出：

• 「過去24時間のブルートフォース攻撃の試行を分析する」
• 「システム内の異常なログイン動作と不審な IP アドレスを検出する」
• 「潜在的な SQL インジェクション攻撃のパターンと悪意のあるリクエストを特定する」
• 「ネットワークフロー内の DDoS 攻撃の特徴とトラフィックの異常を発見する」

根本原因分析：

• 「特定のセキュリティインシデントについて、攻撃チェーン全体と影響範囲を追跡する」
• 「システム障害の根本原因と伝播経路を分析する」
• 「データ侵害の発生源と関係する機密情報を特定する」
• 「タイムラインと操作記録を用いて、ユーザーの権限乱用インシデントを調査する」

脅威インテリジェンス：

• 「ゼロデイ攻撃や未知の脅威を検出する機械学習モデルを作成する」
• 「行動ベースラインを確立し、通常のパターンから逸脱した活動を特定する」
• 「悪意のあるドメインや IP アドレスの脅威レベルと攻撃履歴を分析する」
• 「高度な持続的脅威（APT）の行動特性と攻撃パターンを検出する」

リアルタイム監視：

• 「現在のシステムでアクティブな脅威と進行中の攻撃を監視する」
• 「異常なデータアクセスパターンと権限昇格の動作を検出する」
• 「不審なネットワーク通信とデータ流出活動を発見する」
• 「システムリソース消費の異常やパフォーマンス低下のセキュリティ上の原因を特定する」

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

警告

cluster-admin 権限の使用は避けてください。スコープを限定した専用の API キーを作成し、インデックスレベルで詳細なアクセス制御を適用して、不正なデータアクセスを防いでください。

パッケージの整合性検証

リリースパッケージをダウンロードする際は、整合性を確保するため、必ずチェックサムを検証してください。

# Verify SHA256 checksum
shasum -a 256 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha256

# Verify SHA512 checksum
shasum -a 512 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha512

これにより、次の事態を防げます。

• ダウンロードの破損
• パッケージの改ざん
• 中間者攻撃

Elasticsearch のアクセス制御

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

{
  "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"
          ]
        }
      ]
    }
  }
}

ライセンス

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

トラブルシューティング

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

問題が発生した場合は、GitHub リポジトリでお気軽に issue を作成してください。