このリポジトリには、研究と評価を目的とした実験的な機能が含まれており、実稼働には対応していません。
モデル コンテキスト プロトコル (MCP) を使用して、任意の MCP クライアント (Claude Desktop など) から Elasticsearch データに直接接続します。
このサーバーは、モデルコンテキストプロトコルを使用してエージェントをElasticsearchデータに接続します。これにより、自然言語による会話を通じてElasticsearchインデックスと対話できるようになります。
list_indices : 利用可能なすべてのElasticsearchインデックスを一覧表示する
get_mappings : 特定のElasticsearchインデックスのフィールドマッピングを取得する
search : 提供されたクエリDSLを使用してElasticsearch検索を実行する
get_shards : すべてまたは特定のインデックスのシャード情報を取得する
Related MCP server: Elasticsearch MCP Server
Elasticsearchインスタンス
Elasticsearch 認証資格情報 (API キーまたはユーザー名/パスワード)
MCP クライアント (例: Claude Desktop)
https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c
[!TIP] Elasticsearch MCP Server を使用する最も簡単な方法は、公開されている npm パッケージを使用することです。
MCPクライアントの設定
MCPクライアントを開きます。MCPクライアントのリストを確認し、ここでClaude Desktopを設定します。
設定 > 開発者 > MCP サーバーに移動します
Edit Configをクリックし、次の設定で新しい 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"
}
}
}
}会話を始める
MCPクライアントで新しい会話を開きます
MCPサーバーは自動的に接続されます
Elasticsearchデータについて質問できるようになりました
Elasticsearch MCP サーバーは、Elasticsearch に接続するための構成オプションをサポートしています。
[!NOTE] 認証には、API キーまたはユーザー名とパスワードの両方を指定する必要があります。
環境変数 | 説明 | 必須 |
| ElasticsearchインスタンスのURL | はい |
| 認証用のElasticsearch APIキー | いいえ |
| 基本認証用のElasticsearchユーザー名 | いいえ |
| 基本認証用のElasticsearchパスワード | いいえ |
| Elasticsearch SSL/TLS のカスタム CA 証明書へのパス | いいえ |
[!NOTE] MCP サーバーを変更または拡張する場合は、次のローカル開発手順に従ってください。
正しいNode.jsバージョンを使用する
nvm use依存関係をインストールする
npm installプロジェクトを構築する
npm run buildClaudeデスクトップアプリでローカルに実行
Claudeデスクトップアプリを開く
設定 > 開発者 > MCP サーバーに移動します
Edit Configをクリックし、次の設定で新しい MCP サーバーを追加します。
{
"mcpServers": {
"elasticsearch-mcp-server-local": {
"command": "node",
"args": [
"/path/to/your/project/dist/index.js"
],
"env": {
"ES_URL": "your-elasticsearch-url",
"ES_API_KEY": "your-api-key"
}
}
}
}MCP Inspectorによるデバッグ
ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspectorMCP Inspectorが起動し、リクエストのデバッグと分析が可能になります。以下の画面が表示されます。
Starting MCP inspector...
Proxy server listening on port 3000
🔍 MCP Inspector is up and running at http://localhost:5173 🚀コミュニティからの貢献を歓迎します。貢献方法の詳細については、貢献ガイドラインをご覧ください。
[!TIP] MCP クライアントで試すことができる自然言語クエリをいくつか示します。
「Elasticsearch クラスターにはどのようなインデックスがありますか?」
「「製品」インデックスのフィールド マッピングを表示します。」
「先月の 500 ドルを超えるすべての注文を検索します。」
「5 つ星のレビューを最も多く獲得した製品はどれですか?」
MCP クライアントはリクエストを分析し、必要な Elasticsearch 操作を決定します。
MCP サーバーはこれらの操作 (インデックスの一覧表示、マッピングの取得、検索の実行) を実行します。
MCP クライアントは結果を処理し、ユーザーフレンドリーな形式で表示します。
[!WARNING] クラスター管理者権限の使用は避けてください。スコープを制限した専用のAPIキーを作成し、インデックスレベルできめ細かなアクセス制御を適用して、不正なデータアクセスを防止してください。
データへのアクセスを制御するために、最小限の権限を持つ専用の Elasticsearch 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"
]
}
]
}
}
}このプロジェクトは、Apache License 2.0 に基づいてライセンスされています。
MCP 構成が正しいことを確認してください。
Elasticsearch URL がマシンからアクセスできることを確認します。
認証資格情報 (API キーまたはユーザー名/パスワード) に必要な権限があることを確認します。
カスタム CA で SSL/TLS を使用する場合は、証明書パスが正しいことと、ファイルが読み取り可能であることを確認します。
エラー メッセージのターミナル出力を確認します。
問題が発生した場合は、お気軽に GitHub リポジトリで問題を報告してください。
Get field mappings for a specific Elasticsearch index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to get mappings for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Get field mappings', implying read-only but not disclosing permissions, side effects, or behavior like error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loaded with the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could mention what the response contains; it is adequate but minimal for a simple get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'index' has a description; the tool description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and resource 'field mappings' for a specific Elasticsearch index, clearly distinguishing from siblings like create_mapping or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; for example, it doesn't explain how it differs from create_mapping or search in terms of use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Elasticsearch indices
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'List' implies a read operation, it doesn't specify whether this requires special permissions, returns paginated results, includes hidden/system indices, or provides any metadata beyond names. For a tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a simple listing tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read operation without output schema, the description provides the minimum viable information about what the tool does. However, given the lack of annotations and sibling tools with potentially overlapping functionality, more context about when to use this versus alternatives would be helpful. The description is complete enough for basic understanding but leaves operational context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't mention parameters since none exist. A baseline of 4 is appropriate for zero-parameter tools where the schema handles all parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all available Elasticsearch indices'), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_mappings' or 'search' - it's unclear if this is a simple listing versus more detailed metadata retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_mappings' or 'search'. There's no indication of whether this is for administrative purposes, discovery, or as a prerequisite for other operations. The agent must infer usage context from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an Elasticsearch search with the provided query DSL. Highlights are always enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to search | |
| queryBody | Yes | Complete Elasticsearch query DSL object that can include query, size, from, sort, etc. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Only mentions highlights are always enabled. No disclosure of read-only nature, error handling, pagination, or required permissions. With no annotations, more behavioral detail is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action. No wasted words, though could be expanded with important behavioral notes without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of Elasticsearch searches (query DSL), the description lacks return format, pagination behavior, and error context. Incomplete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes both parameters. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs an Elasticsearch search with query DSL, identifying the specific verb and resource. Distinguishes from sibling tools that handle index management, bulk operations, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over siblings (e.g., bulk, list_indices) or when not to use it. Lacks prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_mappingslist_indicessearchScored across 3 tools
Each tool has a clearly distinct purpose: get_mappings retrieves field mappings for a specific index, list_indices enumerates all indices, and search performs query-based searches. There is no overlap in functionality, making tool selection unambiguous.
All tool names follow a consistent verb_noun pattern (get_mappings, list_indices, search), with clear and descriptive verbs that align with their actions. No deviations or mixed conventions are present.
With only 3 tools, the set feels thin for an Elasticsearch server, as it lacks essential operations like creating/deleting indices, updating mappings, or performing CRUD operations on documents. While the tools are well-defined, the count is borderline for the domain's scope.
There are significant gaps in the tool surface for Elasticsearch functionality. Missing operations include index creation/deletion, document indexing/updating/deleting, and cluster management. This incompleteness will likely cause agent failures when attempting full workflows.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Connect Claude, Cursor, or ChatGPT to your business data. Ask questions, get answers.
Build and manage AI-native customer support agents from Claude or any MCP client.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
