Unofficial Elasticsearch MCP Server

非公式 Elasticsearch MCP サーバー

Claude Desktop などの AI アシスタントを Elasticsearch クラスターに接続する、本番環境対応の Model Context Protocol（MCP）サーバーです。このサーバーでは、自然言語でのやり取りを通じて包括的な Elasticsearch 操作を実行できます。高度な設定管理、セキュリティ制御、豊富なツールを備えています。

Official Elastic MCP Server を包括的に強化したもので、基本ツールを 4 つから 170 以上の専用操作へと拡張し、Elasticsearch エコシステム全体をカバーします。

主な機能

• 包括的なツール群：検索、インデックス作成、クラスター管理、分析、専用ツールなど、170 以上の Elasticsearch 操作
• 高度な設定：環境変数の検証に対応した型安全な設定システム
• セキュリティ制御：本番環境の安全な監視に適した、厳格モードと警告モードを備えた読み取り専用モード
• 高度な検索：自動ハイライト、集計、SQL に対応した高度な検索
• 一括操作：ヘルパー API による効率的な一括インデックス作成、更新、削除
• クラスター監視：ヘルスチェック、ノード統計、パフォーマンス指標
• エラー処理：詳細なログとトラブルシューティングガイドを備えた堅牢なエラー処理
• 自動検出による監視：Grafana ダッシュボード付き Prometheus メトリクス（自動検出し、適切に機能を縮退します）
• サーキットブレーカー：コネクションプーリングとレート制限による、本番環境レベルの高い耐障害性
• マルチエージェント開発：15 以上の専用エージェントを活用し、ワークフローを調整する高度な開発連携
• LangSmith との統合：AI とのやり取りを高度にトレースし、パフォーマンスを監視
• パフォーマンス：最適なパフォーマンスと最新の JavaScript 機能を実現するため、Bun ランタイム上に構築

目次

• 前提条件
• インストール
• クイックスタート
• 設定
• 利用可能なツール
• 使用例
• 開発
• アーキテクチャ
• セキュリティ
• トラブルシューティング

前提条件

Bun のインストール

このプロジェクトでは、最適なパフォーマンスを実現するため、JavaScript ランタイムとして Bun を使用します。次のいずれかの方法で Bun をインストールしてください。

macOS/Linux：

curl -fsSL https://bun.sh/install | bash

Windows（PowerShell）：

irm bun.sh/install.ps1 | iex

パッケージマネージャー：

# npm
npm install -g bun

# Homebrew (macOS)
brew install bun

# Scoop (Windows)
scoop install bun

インストールを確認します。

bun --version

その他の要件

• Bun：最新バージョン（推奨ランタイム）
• Elasticsearch：バージョン 7.x 以降（8.x 以降を推奨）
• MCP クライアント：Claude Desktop、または MCP 互換クライアント
• Node.js：18 以降（必要に応じて npm 互換性のため）

インストール

オプション 1：公開済み NPM パッケージを使用（推奨）

Elasticsearch MCP Server を最も簡単に使用する方法です。

npx @elastic/mcp-server-elasticsearch

オプション 2：ローカル開発環境へのインストール

1. リポジトリをクローンします。

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

2. 依存関係をインストールします。

   bun install
   

3. プロジェクトをビルドします。

   bun run build
   

クイックスタート

1. 環境を設定する

テンプレートから .env ファイルを作成します。

cp .env.example .env

最小限の設定：

# Required
ES_URL=http://localhost:9200

# Authentication (choose one)
ES_API_KEY=your_api_key_here
# OR
ES_USERNAME=elastic
ES_PASSWORD=changeme

# Optional: Enable read-only mode for safety
READ_ONLY_MODE=false
LOG_LEVEL=info

2. 設定を検証する

# Basic validation
bun run validate-config

# Full validation with connection test
bun run validate-config:full

3. MCP クライアント（Claude Desktop）を設定する

MCP クライアントの設定に追加します。

公開済みパッケージの場合：

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "npx",
      "args": ["-y", "@elastic/mcp-server-elasticsearch"],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

ローカル開発の場合：

{
  "mcpServers": {
    "elasticsearch-mcp-server-local": {
      "command": "bun",
      "args": ["run", "/path/to/your/project/src/index.ts"],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

4. 使用を開始する

MCP クライアントを開き、Elasticsearch のデータについて質問します。

• 「クラスターにはどのインデックスがありますか？」
• 「products インデックスのフィールドマッピングを表示してください」
• 「先月の 500 ドルを超える注文をすべて検索してください」

設定

このサーバーには、型安全な検証と環境変数のサポートを備えた包括的な設定システムがあります。

環境変数

必須変数

変数	説明	例
ES_URL	Elasticsearch サーバーの URL	http://localhost:9200

認証（いずれかの方法を選択）

API キー認証（推奨）：

ES_API_KEY=your_api_key_here

ユーザー名／パスワード認証：

ES_USERNAME=your_username
ES_PASSWORD=your_password

サーバー設定

変数	デフォルト	説明
MCP_SERVER_NAME	elasticsearch-mcp-server	サーバーの識別名
MCP_SERVER_VERSION	0.1.1	サーバーのバージョン
READ_ONLY_MODE	false	読み取り専用モードを有効にします
READ_ONLY_STRICT_MODE	true	破壊的な操作をブロックするか、警告するかを指定します
MCP_MAX_QUERY_TIMEOUT	30000	クエリの最大タイムアウト（ms）
MCP_MAX_RESULTS_PER_QUERY	1000	クエリごとの最大結果数
MCP_TRANSPORT	stdio	トランスポートモード（stdio または sse）
MCP_PORT	8080	サーバーのポート（SSE モード用）

Elasticsearch の設定

変数	デフォルト	説明
ES_CA_CERT	-	CA 証明書ファイルのパス
ES_MAX_RETRIES	3	最大再試行回数
ES_REQUEST_TIMEOUT	30000	リクエストのタイムアウト（ms）
ES_COMPRESSION	true	レスポンスの圧縮を有効にします
ES_ENABLE_META_HEADER	true	クライアントメタヘッダーを有効にします
ES_DISABLE_PROTOTYPE_POISONING_PROTECTION	true	プロトタイプ保護を無効にします

ログ設定

変数	デフォルト	説明
LOG_LEVEL	info	ログレベル（debug、info、warn、error）
LOG_FORMAT	json	ログ形式（json または text）
LOG_INCLUDE_METADATA	true	ログにメタデータを含めます

設定例

ローカル開発

ES_URL=http://localhost:9200
LOG_LEVEL=debug
READ_ONLY_MODE=false

API キーを使用した本番環境

ES_URL=https://your-cluster.es.cloud.aws.com:443
ES_API_KEY=your_production_api_key
READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=true
LOG_LEVEL=info
ES_MAX_RETRIES=5
ES_REQUEST_TIMEOUT=60000

Elastic Cloud

ES_URL=https://your-deployment.es.us-central1.gcp.cloud.es.io:443
ES_API_KEY=your_cloud_api_key
READ_ONLY_MODE=true
LOG_LEVEL=info

TLS を使用したセルフホスト環境

ES_URL=https://elasticsearch.company.com:9200
ES_USERNAME=mcp_user
ES_PASSWORD=secure_password
ES_CA_CERT=/etc/ssl/certs/elasticsearch-ca.pem
READ_ONLY_MODE=true
LOG_LEVEL=warn

読み取り専用モード

このサーバーは、本番環境で安全に操作するための読み取り専用モードをサポートしています。

厳格モード（本番環境）

READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=true

• すべての破壊的な操作をブロックします
• 書き込み／削除操作に対してエラーレスポンスを返します
• モニタリングや分析に最適です

警告モード（開発環境）

READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=false

• 警告を明示して操作を許可します
• 破壊的な操作について警告をログに記録します
• テストや管理された環境に適しています

利用可能なツール

コア操作

• list_indices - 利用可能なすべての Elasticsearch インデックスを一覧表示します
• get_mappings - インデックスのフィールドマッピングを取得します
• search - 自動ハイライト付きで検索を実行します
• get_shards - シャードの情報と分布を取得します

ドキュメント操作

• get_document - ID を指定してドキュメントを取得します
• index_document - ドキュメントを作成または更新します (書き込み操作)
• update_document - 既存のドキュメントを更新します (書き込み操作)
• delete_document - ドキュメントを削除します (破壊的な操作)
• document_exists - ドキュメントが存在するか確認します

一括操作

• bulk_operations - 作成／更新／削除を効率的に一括実行します (書き込み／破壊的な操作)
• multi_get - 複数のドキュメントを取得します

検索と分析

• execute_sql_query - SQL クエリを実行します
• count_documents - 条件に一致するドキュメント数を数えます
• scroll_search - 大量の検索結果を処理します
• multi_search - 複数の検索を実行します
• update_by_query - ドキュメントを一括更新します (書き込み操作)
• delete_by_query - ドキュメントを一括削除します (破壊的な操作)
• clear_scroll - リソースを解放するため、スクロールコンテキストをクリアします

インデックス管理

• create_index - 新しいインデックスを作成します (書き込み操作)
• delete_index - インデックスを削除します (破壊的操作)
• index_exists - インデックスの存在を確認します
• get_index - インデックス情報を取得します
• get_index_settings - インデックス設定を取得します
• update_index_settings - インデックス設定を変更します (書き込み操作)
• put_mapping - インデックスのマッピングを更新します (書き込み操作)
• refresh_index - インデックスを強制的にリフレッシュします (書き込み操作)
• flush_index - インデックスを強制的にフラッシュします (書き込み操作)
• reindex_documents - インデックス間でデータをコピー／移動します (書き込み操作)

テンプレート管理

• search_template - 保存済みの検索テンプレートを実行します
• multi_search_template - 複数の検索テンプレートを実行します
• get_index_template - インデックステンプレートの定義を取得します
• put_index_template - インデックステンプレートを作成または更新します (書き込み操作)
• delete_index_template - インデックステンプレートを削除します (破壊的操作)

分析と用語解析

• get_term_vectors - ドキュメントの用語ベクトルを取得します
• get_multi_term_vectors - 複数のドキュメントの用語ベクトルを取得します

インデックスエイリアス

• get_aliases - インデックスエイリアスを取得します
• put_alias - インデックスエイリアスを作成します (書き込み操作)
• delete_alias - インデックスエイリアスを削除します (破壊的操作)
• update_aliases - 複数のエイリアスをアトミックに更新します (書き込み操作)

クラスター管理

• get_cluster_health - クラスターのヘルスステータスを取得します
• get_cluster_stats - クラスターの統計情報を取得します
• get_nodes_info - ノード情報を取得します
• get_nodes_stats - ノードの統計情報を取得します

フィールドマッピングと SQL 管理

• get_field_mapping - 特定のフィールドマッピングを取得します
• clear_sql_cursor - SQL カーソルをクリアします
• translate_sql_query - SQL を Elasticsearch DSL に変換します

インデックスライフサイクル管理（ILM）

• ilm_get_lifecycle - ライフサイクルポリシーを取得します
• ilm_put_lifecycle - ライフサイクルポリシーを作成または更新します (書き込み操作)
• ilm_delete_lifecycle - ライフサイクルポリシーを削除します (破壊的操作)
• ilm_explain_lifecycle - インデックスのライフサイクル状態を説明します
• ilm_get_status - ILM のステータスを取得します
• ilm_start - ILM プラグインを開始します (書き込み操作)
• ilm_stop - ILM プラグインを停止します (書き込み操作)
• ilm_retry - 失敗したライフサイクルステップを再試行します (書き込み操作)
• ilm_remove_policy - インデックスからポリシーを削除します (書き込み操作)
• ilm_move_to_step - インデックスをライフサイクルステップに手動で移動します (破壊的操作)
• ilm_migrate_to_data_tiers - データティアに移行します (破壊的操作)

エンリッチポリシー

• enrich_get_policy - エンリッチポリシーの情報を取得します
• enrich_put_policy - エンリッチポリシーを作成します (書き込み操作)
• enrich_delete_policy - エンリッチポリシーを削除します (破壊的操作)
• enrich_execute_policy - エンリッチポリシーを実行します (書き込み操作)
• enrich_stats - エンリッチ統計情報を取得します

Watcher 操作

• watcher_put_watch - ウォッチを作成または更新します (書き込み操作)
• watcher_get_watch - ウォッチ定義を取得します
• watcher_delete_watch - ウォッチを削除します (破壊的操作)
• watcher_execute_watch - ウォッチを実行します (書き込み操作)
• watcher_ack_watch - ウォッチを確認します (書き込み操作)
• watcher_activate_watch - ウォッチを有効化します (書き込み操作)
• watcher_deactivate_watch - ウォッチを無効化します (書き込み操作)
• watcher_stats - Watcher の統計情報を取得します
• watcher_start - Watcher サービスを開始します (書き込み操作)
• watcher_stop - Watcher サービスを停止します (書き込み操作)

オートスケーリング

• autoscaling_get_policy - オートスケーリングポリシーを取得します
• autoscaling_put_policy - オートスケーリングポリシーを作成します (書き込み操作)
• autoscaling_delete_policy - オートスケーリングポリシーを削除します (破壊的操作)
• autoscaling_get_capacity - オートスケーリングの容量を取得します

高度な操作

• reindex_with_notifications - 進行状況の通知付きで再インデックスを作成します（書き込み操作）
• bulk_index_with_progress - 進行状況を追跡しながら一括でインデックスを作成します（書き込み操作）
• elasticsearch_diagnostics - クラスターの包括的な診断を行います
• analyze_timestamps - データ品質の問題を検出するためにタイムスタンプフィールドを分析します

使用例

自然言語でのクエリ

"What indices do I have in my cluster?"
"Show me the field mappings for the 'products' index"
"Count how many documents are in the logs index"
"What's the health status of my cluster?"

複雑な検索の例

"Search for users with email containing 'gmail' in the users index"
"Find all error logs from the last 24 hours with severity high"
"Show me products with price between 100 and 500 sorted by popularity"
"Get aggregated sales data grouped by region and month"

管理操作

"Create a new index called 'user-analytics' with timestamp mapping"
"Show me the cluster health and node information"
"List all indices that haven't been accessed in the last week"
"Update the refresh interval for the logs index to 30 seconds"

開発

利用可能なスクリプト

# Development
bun run dev # Start in development mode
bun run build # Build for production
bun run start # Start built server

# Configuration Management
bun run validate-config # Validate configuration
bun run validate-config:full # Full validation + connection test
bun run test-connection # Test Elasticsearch connection

# Quality & Testing
bun run test # Run tests
bun run lint # Lint code
bun run format # Format code

# Debugging
bun run inspector # Start MCP inspector for debugging

開発環境のセットアップ

1. クローンしてセットアップします：

   git clone <repository>
   cd mcp-server-elasticsearch
   bun install
   

2. 開発環境を作成します：

   cp .env.example .env.dev
   # Edit .env.dev with your local settings
   

3. 開発サーバーを起動します：

   bun run dev
   

4. MCP Inspector でデバッグします：

   ES_URL=your-url ES_API_KEY=your-key bun run inspector
   

   Inspector インターフェースを開くには、http://localhost:5173 にアクセスします。

テスト構成

# Test configuration validity
bun run validate-config

# Test with connection verification
bun run validate-config:full --check-connection

# Show all configuration details
bun run validate-config --show-all

アーキテクチャ

プロジェクト構成

src/
 config.ts # Centralized configuration system
 index.ts # Entry point and server startup
 server.ts # MCP server creation and setup
 validation.ts # Environment and connection validation
 tools/ # Tool implementations
    index.ts # Tool registration
    core/ # Core operations (search, list, mappings)
    document/ # Document operations
    search/ # Advanced search operations
    index_management/ # Index management tools
    cluster/ # Cluster monitoring tools
    bulk/ # Bulk operations
    analytics/ # Analytics and term vectors
    alias/ # Index alias management
    template/ # Template management
    advanced/ # Advanced operations
    mapping/ # Field mapping tools
    ilm/ # Index Lifecycle Management
    enrich/ # Enrich policies
 utils/
     logger.ts # MCP-compatible logging system
     readOnlyMode.ts # Read-only mode management

構成システム

このサーバーでは、高度な構成システムを使用しています。

• 型安全性：Zod スキーマによる完全な TypeScript サポート
• 環境変数を優先：環境変数による構成
• 検証：起動時に自動検証
• 階層化：デフォルト値 → 環境変数 → 検証
• ドキュメント：明確な例を含む自己文書化

読み取り専用モードの実装

• 操作の分類：破壊的な可能性に応じてツールを分類
• 柔軟なモード：厳格なブロックと警告モード
• きめ細かな制御：操作タイプごとのチェック
• ログとの統合：包括的な監査証跡

セキュリティ

ベストプラクティス

1. API キーを使用：ユーザー名とパスワードよりも API キー認証を優先します
2. 最小権限の原則：権限を最小限に抑えた専用の API キーを作成します
3. 本番環境では読み取り専用にする：本番環境の監視では読み取り専用モードを有効にします
4. ネットワークセキュリティ：接続には TLS/SSL を使用します
5. 認証情報の管理：認証情報は環境変数に保存します

セキュアな API キーの作成

POST /_security/api_key
{
  "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"]
        }
      ]
    }
  }
}

読み取り専用モードでの操作

常に保護（破壊的）：

• delete_document、delete_index、delete_by_query
• delete_alias、delete_index_template

保護対象（書き込み／変更）：

• index_document、update_document、bulk_operations
• create_index、update_index_settings、put_mapping

常に許可（読み取り専用）：

• search、get_document、list_indices
• get_mappings、count_documents、get_cluster_health

トラブルシューティング

よくある問題

構成エラー

無効な URL 形式：

Error: ES_URL is not a valid URL format

**解決策：**URL に http:// または https:// のプロトコルが含まれていることを確認します。

認証情報がありません：

Error: Either ES_API_KEY or both ES_USERNAME and ES_PASSWORD must be provided

**解決策：**認証情報をすべて指定します。

接続の問題

接続拒否：

Error: ECONNREFUSED

**解決策：**Elasticsearch が実行中であり、URL が正しいことを確認します。

SSL/TLS の問題：

Error: certificate verify failed

解決策：ES_CA_CERT を使用するか、証明書の構成を確認します。

認証に失敗しました：

Error: 401 Unauthorized

**解決策：**API キー、またはユーザー名とパスワードが正しいことを確認します。

読み取り専用モード

操作がブロックされる：

 READ-ONLY MODE: DESTRUCTIVE DELETE operation blocked

解決策：READ_ONLY_MODE=false に設定するか、読み取り専用操作のみを使用します。

デバッグモード

詳細なトラブルシューティングのためにデバッグログを有効にします。

LOG_LEVEL=debug bun run dev

検証ツール

# Check configuration
bun run validate-config

# Test connection
bun run validate-config:full

# Test specific operations
bun run test-connection

MCP Inspector

MCP プロトコルの問題をデバッグするには：

bun run inspector

MCP 通信を調査するには、http://localhost:6274 を開きます。

開発ワークフロー

1. リポジトリをフォークしてクローンします
2. main から機能ブランチを作成します
3. テストを追加して変更を加えます
4. 品質チェックを実行します：

   bun run lint
   bun run format
   bun run test
   bun run validate-config
   

5. 明確な説明を添えてプルリクエストを送信します

コード標準

• TypeScript：厳格な型チェックを有効化
• ESLint：提供された構成によるコードのリント
• Prettier：提供された構成によるコードのフォーマット
• Zod：構成のスキーマ検証
• テスト：包括的なテストカバレッジが必須

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については LICENSE を参照してください。

リンク

• Model Context Protocol
• Elasticsearch Documentation
• Bun Runtime
• Claude Desktop

パフォーマンス

最適なパフォーマンスを実現するため、Bun ランタイム上に構築されています。

• 高速な起動：サーバーをすばやく初期化します
• メモリ効率：メモリ使用量を最適化しています
• モダンな JavaScript：最新の ECMAScript 機能を使用しています
• TypeScript ネイティブ対応：開発時のコンパイルオーバーヘッドがありません

---

**お困りですか？**よくある解決方法については、トラブルシューティングガイドをご確認ください。