이 저장소에는 연구 및 평가를 위한 실험적 기능이 포함되어 있으며, 아직 실제 운영에 적용할 준비가 되지 않았습니다.
Model Context Protocol(MCP)을 사용하여 모든 MCP 클라이언트(예: Claude Desktop)에서 Elasticsearch 데이터에 직접 연결합니다.
이 서버는 모델 컨텍스트 프로토콜(Model Context Protocol)을 사용하여 에이전트를 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 서버를 사용하는 가장 쉬운 방법은 게시된 npm 패키지를 사용하는 것입니다.
MCP 클라이언트 구성
MCP 클라이언트를 엽니다. MCP 클라이언트 목록을 확인하세요. 여기서는 Claude Desktop을 구성하고 있습니다.
설정 > 개발자 > MCP 서버 로 이동하세요.
Edit Config 클릭하고 다음 구성으로 새 MCP 서버를 추가합니다.
지엑스피1
대화 시작하기
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 Desktop App에서 로컬로 실행
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 inspector그러면 MCP 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 클라이언트는 결과를 처리하여 사용자 친화적인 형식으로 표시합니다.
[!경고] 클러스터 관리자 권한 사용을 피하세요. 제한된 범위의 전용 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.
