MCP Elasticsearch Server 🔍

MCP Elasticsearch Server 🔍

AI アシスタントやその他の MCP クライアントに Elasticsearch との連携機能を提供する Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、標準化されたインターフェースを通じて Elasticsearch クラスターにクエリを実行できます。

機能

• 🔐 複数の認証方式：API キー認証とユーザー名／パスワード認証の両方に対応
• 📊 インデックス管理：ヘルスステータスとドキュメント数を含むインデックス一覧を取得
• 🗺️ スキーマの検出：フィールドマッピングを取得してインデックス構造を把握
• 🔍 高度な検索：集計やソートを含む複雑な Elasticsearch クエリを実行
• 📋 構造化されたレスポンス：検索メタデータを含む JSON 形式の出力
• ⚡ パフォーマンスのモニタリング：クエリの実行時間を追跡
• 🎯 コンテキスト対応：適切なコンテキストキャンセルを伴う検索実行に対応

ツール

list_indices

オプションのパターンフィルターを使用して、すべての Elasticsearch インデックスを一覧表示します。

パラメーター：

• pattern（文字列、任意）：インデックスパターンのフィルター（デフォルト：「*」）

戻り値：

• インデックスの合計数
• インデックスの詳細（名前、ヘルス、ステータス、ドキュメント数、サイズ）

get_index_mappings

1 つ以上の Elasticsearch インデックスのフィールドマッピングを取得します。

パラメーター：

• index（文字列、必須）：インデックス名またはパターン

戻り値：

• 指定したインデックスの完全なフィールドマッピング

search

完全な DSL サポートで Elasticsearch 検索クエリを実行します。

パラメーター：

• index（文字列、必須）：検索対象のインデックス名またはパターン
• query（文字列、任意）：JSON 形式の Elasticsearch クエリ DSL（デフォルト：「{}」）
• size（数値、任意）：返すドキュメントの最大数（デフォルト：10、最大：10000）
• sort（文字列、任意）：JSON 形式のソート指定
• track_total_hits（ブール値、任意）：ヒット総数を追跡するかどうか（デフォルト：true）

戻り値：

• ヒット、集計、メタデータを含む検索結果

設定

環境変数

Elasticsearch の設定

• ES_URL：Elasticsearch クラスターの URL（必須）
• ES_API_KEY：認証用の API キー（任意）
• ES_USERNAME：基本認証用のユーザー名（任意）
• ES_PASSWORD：基本認証用のパスワード（任意）

サーバーの設定

• MCP_ES_SERVER_NAME：サーバー名（デフォルト：「mcp-elasticsearch 🔍」）

ロギングの設定

• MCP_ES_LOG_LEVEL：ログレベル（debug、info、warn、error、fatal）
• MCP_ES_LOG_FORMAT：ログ形式（json、console）
• MCP_ES_LOG_OUTPUT：ログ出力先（stdout、stderr）

認証

次のいずれかを設定する必要があります。

1. API キー認証：ES_API_KEY を設定
2. 基本認証：ES_USERNAME と ES_PASSWORD の両方を設定

インストール

# Clone and build
git clone <repository>
cd mcp-elasticsearch
go mod download
go build -o bin/mcp-elasticsearch .

# Install to system
sudo install bin/mcp-elasticsearch /usr/local/bin/

使い方

直接実行

# With API key
ES_URL="https://your-cluster.com" ES_API_KEY="your-api-key" mcp-elasticsearch

# With basic auth
ES_URL="https://your-cluster.com" ES_USERNAME="user" ES_PASSWORD="pass" mcp-elasticsearch

# With custom logging
ES_URL="https://your-cluster.com" ES_API_KEY="key" MCP_ES_LOG_LEVEL=debug mcp-elasticsearch

Claude Desktop との連携

Claude の設定に追加します。

{
  "mcpServers": {
    "elasticsearch": {
      "command": "mcp-elasticsearch",
      "env": {
        "ES_URL": "https://your-cluster.com",
        "ES_API_KEY": "your-api-key",
        "MCP_ES_LOG_LEVEL": "info"
      }
    }
  }
}

ApMentor との連携

config.json を更新します。

{
  "mcpServers": {
    "elasticsearch-go": {
      "command": "/usr/local/bin/mcp-elasticsearch",
      "env": {
        "ES_URL": "https://atani.es.eu-west-1.aws.found.io",
        "ES_API_KEY": "your-api-key",
        "MCP_ES_LOG_LEVEL": "info"
      }
    }
  }
}

クエリの例

すべてのインデックスを一覧表示

{
  "tool": "list_indices",
  "parameters": {
    "pattern": "*"
  }
}

ログインデックスのみを一覧表示

{
  "tool": "list_indices", 
  "parameters": {
    "pattern": "logs-*"
  }
}

インデックスマッピングを取得

{
  "tool": "get_index_mappings",
  "parameters": {
    "index": "logs-apm.error-*"
  }
}

シンプルな検索

{
  "tool": "search",
  "parameters": {
    "index": "logs-*",
    "query": "{\"match\": {\"service.name\": \"broker-api-b2b\"}}",
    "size": 50
  }
}

集計を使った複雑な検索

{
  "tool": "search",
  "parameters": {
    "index": "logs-*",
    "query": "{\"bool\": {\"must\": [{\"term\": {\"service.name\": \"broker-api-b2b\"}}, {\"range\": {\"@timestamp\": {\"gte\": \"now-24h\"}}}]}}",
    "size": 0,
    "aggs": "{\"error_types\": {\"terms\": {\"field\": \"error.type.keyword\", \"size\": 10}}}"
  }
}

ソートを使った検索

{
  "tool": "search",
  "parameters": {
    "index": "logs-*",
    "query": "{\"match\": {\"log.level\": \"ERROR\"}}",
    "sort": "[{\"@timestamp\": {\"order\": \"desc\"}}]",
    "size": 20
  }
}

開発

# Install dependencies
go mod download

# Format code
gofmt -w .

# Run tests
go test -v ./...

# Build
go build -o bin/mcp-elasticsearch .

# Run with debug logging
MCP_ES_LOG_LEVEL=debug go run .

エラー処理

このサーバーは、一般的な問題について詳細なエラーメッセージを提供します。

• 認証エラー：API キーまたは認証情報を確認してください
• インデックスが見つからない：インデックス名とパターンを確認してください
• クエリ構文エラー：Elasticsearch クエリの JSON が正しいか確認してください
• 接続の問題：Elasticsearch にアクセスできることを確認してください

セキュリティ上の考慮事項

• API キーと認証情報は安全に保管してください
• 機密性の高い設定には環境変数を使用してください
• Elasticsearch へのアクセスに関するネットワークセキュリティを検討してください
• クエリのパターンとリソースの使用状況を監視してください

ライセンス

MIT License — 詳細については LICENSE ファイルを参照してください。