기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# OpenSearch MCP 서버
[OpenSearch MCP 서버](https://github.com/opensearch-project/opensearch-mcp-server-py)(`opensearch-mcp-server-py`)는 OpenSearch용 [모델 컨텍스트 프로토콜](https://modelcontextprotocol.io)의 오픈 소스 구현입니다. OpenSearch APIs를 AI 어시스턴트 및 에이전트 프레임워크가 직접 호출할 수 있는 도구로 노출하므로 *"내 클러스터에 어떤 인덱스가 있나요?"*와 같은 질문을 할 수 있습니다. 또는 *"지난 한 시간 동안의 가장 느린 쿼리 표시"* 및 에이전트가 사용자를 대신하여 API 호출을 처리합니다.
서버는 관리형 OpenSearch Service 도메인과 OpenSearch Serverless 컬렉션 모두에서 작동합니다. 이를 코딩 IDEs(Kiro, Claude Code, Cursor), 데스크톱 AI 어시스턴트(Claude Desktop) 및 에이전트 프레임워크(Strands Agents, LangGraph)에 연결할 수 있습니다.
## 사전 조건
+ Python 3.10 이상.
+ [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/) (권장) 또는 `pip`.
+ 연결 가능한 OpenSearch 엔드포인트: OpenSearch Service 도메인, OpenSearch Serverless 컬렉션 또는 자체 관리형 OpenSearch 클러스터.
+ 노출하려는 OpenSearch APIs를 호출할 수 있는 권한이 있는 자격 증명입니다. OpenSearch Service 도메인에 대한 IAM 정책은 섹션을 참조하세요[ID 기반 정책](ac.md#ac-types-identity). OpenSearch Serverless 데이터 액세스 정책은 섹션을 참조하세요[Amazon OpenSearch Serverless를 위한 데이터 액세스 제어](serverless-data-access.md).
## 설치
`uvx` (설치 필요 없음)를 사용하여 서버를 실행하거나 로컬에 설치합니다.
```
# Run directly with uvx (recommended – no install step)
uvx opensearch-mcp-server-py
# Or install with pip
pip install opensearch-mcp-server-py
```
대부분의 사용자는 서버를 자동으로 시작하도록 IDE 또는 AI 어시스턴트를 구성합니다. 예제는 [코딩 IDE에서 구성](mcp-server-configure-ide.md) 및 단원[에이전트 프레임워크와 함께 사용](mcp-server-configure-frameworks.md)을 참조하십시오.
## Authentication
환경 변수(단일 클러스터 모드)를 통해 또는 YAML 구성 파일의 클러스터당(다중 클러스터 모드) 인증을 구성합니다. 서버는 인증 없음, 헤더 기반, IAM 역할, 기본 인증, AWS 액세스 키의 우선 순위에 따라 인증 방법을 적용합니다.
**IAM 역할(SigV4) - OpenSearch Service 도메인에 권장**
```
export OPENSEARCH_URL="{{https://your-domain-endpoint}}"
export AWS_IAM_ARN="arn:aws:iam::{{123456789012}}:role/{{YourOpenSearchRole}}"
export AWS_REGION="{{us-east-1}}"
```
역할에는 서버에서 사용하는 OpenSearch APIs를 호출할 수 있는 권한이 있어야 합니다. 샘플 정책은 섹션을 참조[추가 샘플 정책](ac.md#ac-samples)하세요.
**AWS 자격 증명 또는 프로필**
```
export OPENSEARCH_URL="{{https://your-domain-endpoint}}"
export AWS_REGION="{{us-east-1}}"
export AWS_PROFILE="{{your-aws-profile}}"
```
**OpenSearch Serverless 컬렉션**
서버가 대신 `aoss` 서비스 이름으로 요청에 서명`AWS_OPENSEARCH_SERVERLESS=true`하도록를 설정합니다`es`. 보안 주체에게 컬렉션의 데이터 액세스 정책을 통해 액세스 권한이 부여되었는지 확인합니다( 참조[Amazon OpenSearch Serverless를 위한 데이터 액세스 제어](serverless-data-access.md)).
```
export OPENSEARCH_URL="{{https://collection-id.us-east-1.aoss.amazonaws.com}}"
export AWS_OPENSEARCH_SERVERLESS="true"
export AWS_REGION="{{us-east-1}}"
export AWS_PROFILE="{{your-aws-profile}}"
```
**기본 인증**
```
export OPENSEARCH_URL="{{https://your-domain-endpoint}}"
export OPENSEARCH_USERNAME="{{username}}"
export OPENSEARCH_PASSWORD="{{password}}"
```
소스 제어에 체크인할 수 있는 구성 파일에 암호를 포함하지 마십시오. 운영 체제의 보안 암호 관리자 또는 셸 환경을 사용하여 자격 증명을 제공합니다.
## 보안 고려 사항
MCP 서버는 사용자가 제공한 자격 증명으로 실행됩니다. 이러한 자격 증명이 승인되면 AI 어시스턴트가 사용자를 대신하여 트리거할 수 있습니다. 다음 관행을 따릅니다.
+ **최소 권한 자격 증명을 사용합니다.** 에이전트에게 필요한 인덱스 및 작업으로 범위가 지정된 전용 IAM 역할 또는 OpenSearch 사용자를 생성합니다. 관리자 자격 증명을 재사용하지 마세요.
+ **개발과 프로덕션을 구분합니다.** 탐색을 위해 서버를 비프로덕션 클러스터로 가리킵니다. 프로덕션 액세스가 필요한 경우 명시적 클러스터 이름과 함께 다중 모드를 사용합니다.
+ **필터 도구.** 워크플로에 필요하지 않은 도구 범주를 비활성화합니다. 기본 세트를 비활성화`OPENSEARCH_DISABLED_CATEGORIES=core_tools`하도록 설정하거나 `OPENSEARCH_ENABLED_CATEGORIES`를 사용하여 특정 범주만 활성화합니다.
+ **자격 증명을 보호합니다.** 정적 액세스 키보다 프로필과 IAM 역할을 선호 AWS 합니다. 소스 제어의 구성 파일에 암호를 커밋하지 마십시오.
+ **도구 출력을 검토합니다.** MCP 도구 응답은 컨텍스트로 언어 모델에 다시 제공됩니다. AI 공급자에게 노출하지 않으려는 민감한 데이터가 포함된 인덱스에 대해 서버를 실행하지 마세요.
## 문제 해결
**어시스턴트에 OpenSearch 도구가 표시되지 않습니다.**
구성 파일이 유효한 JSON인지 확인하고 클라이언트를 완전히 다시 시작합니다. 대부분의 클라이언트는 시작 시 MCP 서버만 로드합니다.
**도구 호출은 403 Forbidden을 반환합니다.**
자격 증명에는 도구가 호출하는 API에 대한 권한이 없습니다. OpenSearch Service 도메인의 경우 역할에 연결된 도메인 액세스 정책 및 IAM 정책을 검토합니다. OpenSearch Serverless의 경우 컬렉션의 데이터 액세스 정책을 검토합니다.
**OpenSearch Serverless의 서명 불일치 오류**
`AWS_OPENSEARCH_SERVERLESS=true`가 설정되어 있는지 확인합니다(또는 `is_serverless: true` 다중 모드에서). 그렇지 않으면 서버가 대신 `es` 서비스 이름으로 서명합니다`aoss`.
**필요한 도구를 사용할 수 없음**
기본이 아닌 범주에 있는지 확인하고 YAML 구성`enabled_categories`에서 `OPENSEARCH_ENABLED_CATEGORIES` 또는를 사용하여 활성화합니다.
추가 도움이 필요하면 [opensearch-mcp-server-py 리포지토리](https://github.com/opensearch-project/opensearch-mcp-server-py/issues)에서 문제를 엽니다.
## 추가 리소스
+ GitHub의 [opensearch-mcp-server-py](https://github.com/opensearch-project/opensearch-mcp-server-py) – 소스, 문제 및 릴리스 정보.
+ [사용 설명서](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md) - 스트리밍 전송 및 Kubernetes 배포를 포함한 전체 구성 참조입니다.
+ [Strands Agents](https://strandsagents.com) AWS- MCP 지원이 내장된 네이티브 에이전트 SDK입니다.
+ [LangGraph](https://github.com/langchain-ai/langgraph) - 상태 저장 에이전트를 위한 하위 수준 오케스트레이션 프레임워크입니다.
+ [OpenSearch 에이전트 기술](opensearch-agent-skills.md) - 작업 중심 워크플로를 위한 컴패니언 스킬 컬렉션입니다.