Elasticsearch MCP Server

Elasticsearch MCP 서버

소개

Elasticsearch Model Context Protocol(MCP) 서버는 Spring AI MCP를 기반으로 개발된 서버 애플리케이션입니다. MCP를 통해 다양한 데이터 처리 워크플로를 쉽게 정의하고 Elasticsearch 클러스터에서 결과를 효율적으로 인덱싱하고 검색하도록 설계되었습니다.

주요 특징

• 자동 MCP 도구 등록 및 실행 : Spring Boot 환경에서 @Tool 애노테이션으로 정의된 기능은 MCP 서버에 자동으로 등록됩니다. 이를 통해 외부 클라이언트(예: Claude, FastMCP CLI)가 표준 JSON-RPC 기반 통신을 통해 이러한 함수를 호출할 수 있습니다.
• Elasticsearch 클러스터 통합 : 공식 Elasticsearch Java 클라이언트를 사용하여 클러스터 상태 점검, 인덱스 매핑 조회, 문서 인덱싱 및 검색과 같은 주요 Elasticsearch API를 쉽게 호출하고 MCP 도구 형태로 결과를 제공합니다.
• 확장 가능한 아키텍처 : 모듈식 패키지 구조를 통해 다양한 Elasticsearch 버전에 대한 클라이언트 설정을 유연하게 분리하고 관리할 수 있습니다. 또한 새로운 도구나 외부 통합 기능을 쉽게 추가할 수 있도록 설계되었습니다.

사용 가능한 MCP 도구

• get_cluster_health : Elasticsearch 클러스터의 상태에 대한 기본 정보를 반환합니다.
• get_cluster_statistics : 클러스터 이름, UUID, 상태, 노드 역할, OS 및 JVM 리소스 사용량, 인덱스 수, 샤드 메트릭을 포함한 포괄적인 클러스터 통계를 검색합니다.
• get_cat_mappings : 특정 Elasticsearch 인덱스에 대한 필드 매핑 정보를 검색합니다.
• get_cat_indices : Elasticsearch의 모든 인덱스 목록을 검색합니다.
• get_cat_indices_by_name : 지정된 인덱스 이름이나 와일드카드 패턴과 일치하는 인덱스 목록을 검색합니다.
• get_cat_aliases : Elasticsearch에 있는 모든 별칭 목록을 검색합니다.
• get_cat_aliases_by_name : 지정된 별칭 이름이나 와일드카드 패턴과 일치하는 별칭 목록을 검색합니다.
• get_document_search_by_index : AI가 생성한 쿼리 DSL을 사용하여 Elasticsearch 인덱스 내에서 문서를 검색합니다.
• get_shard_allocation : Elasticsearch 클러스터의 샤드 할당에 대한 정보를 반환합니다.
• get_shard_allocation_for_node : Elasticsearch 클러스터의 특정 노드에 대한 샤드 할당에 대한 정보를 반환합니다.

기술 스택

• 언어 : Java 17
• 프레임워크 : Spring Boot 3.4.5, Spring AI MCP
• 검색 엔진 : Elasticsearch 7.16 이상
• 빌드 도구 : Gradle 8.12

필수 조건

이 프로젝트를 빌드하고 실행하려면 다음 소프트웨어가 필요합니다.

• JDK: 버전 17 이상
• Elasticsearch 인스턴스 실행: 버전 7.16 이상
• MCP 클라이언트(예: Claude Desktop)

설치 및 실행

로컬 환경에서 프로젝트를 설정하고 실행하는 방법은 다음과 같습니다.

1. 소스 코드 복제

지엑스피1

2. mcp-server 모듈에서 application.yml 구성합니다.

Elasticsearch 클러스터 정보를 설정하려면 mcp-server/src/main/resources/application.yml 에 있는 application.yml 파일을 엽니다.

3. 빌드

다음 명령을 사용하여 프로젝트를 빌드합니다.

• 빌드된 JAR 파일은 mcp-server/build/libs/ 디렉토리에서 찾을 수 있습니다.

4. MCP 클라이언트 구성

• MCP 클라이언트를 실행하세요. (MCP 클라이언트 목록은 MCP 클라이언트 목록 에서 확인할 수 있습니다. 이 가이드에서는 Claude Desktop을 예시로 사용합니다.)
• MCP 클라이언트의 설정 메뉴에서 '개발자' > 'MCP 서버'로 이동합니다.
• '구성 편집' 버튼을 클릭하고 다음 내용으로 새 MCP 서버 구성을 추가하세요. (앞서 빌드한 JAR 파일의 실제 경로를 사용해야 합니다.)
  { "mcpServers": { "elasticsearch-server": { "command": "java", "args": [ "-Dusername=YOUR_USERNAME", "-Dpassword=YOUR_PASSWORD", "-jar", "/path/to/your/mcp-server.jar" ] } } }
• -Dusername (선택 사항): Elasticsearch 클러스터에 액세스하는 데 필요한 사용자 ID를 지정합니다(예: -Dusername=elastic )
• -Dpassword (선택 사항): Elasticsearch 클러스터에 액세스하는 데 필요한 비밀번호를 지정합니다(예: -Dpassword=yoursecurepassword )
• /path/to/your/mcp-server.jar : 이것은 빌드한 mcp-server.jar 파일의 실제 전체 경로로 대체되어야 합니다.