MCP + Milvus: AI와 벡터 데이터베이스의 연결

소개

MCP(모델 컨텍스트 프로토콜) 는 Claude 및 Cursor와 같은 AI 애플리케이션이 외부 데이터 소스 및 툴과 원활하게 상호 작용할 수 있도록 지원하는 개방형 프로토콜입니다. 맞춤형 AI 애플리케이션을 구축하든, AI 워크플로를 통합하든, 채팅 인터페이스를 개선하든, MCP는 대규모 언어 모델(LLM)을 관련 문맥 데이터와 연결하는 표준화된 방법을 제공합니다.

이 튜토리얼에서는 사용자 지정 데이터베이스 쿼리를 작성하지 않고도AI 애플리케이션이 벡터 검색을 수행하고, 컬렉션을 관리하고, 자연어 명령을사용하여 데이터를 검색할 수 있도록 Milvus용 MCP 서버를 설정하는 방법을 안내합니다.

전제 조건

MCP 서버를 설정하기 전에 다음이 필요합니다:

• Python 3.10 이상
• 실행 중인 Milvus 인스턴스
• UV (서버 실행에 권장)

시작하기

이 MCP 서버를 사용하는 권장 방법은 설치 없이 uv로 직접 실행하는 것입니다. 아래 예제에서 Claude 데스크톱과 커서가 이 서버를 사용하도록 구성한 방식입니다.

리포지토리를 복제하려는 경우:

git clone https://github.com/zilliztech/mcp-server-milvus.git
cd mcp-server-milvus

서버를 직접 실행할 수 있습니다:

uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

지원되는 애플리케이션

이 MCP 서버는 다음과 같이 모델 컨텍스트 프로토콜을 지원하는 다양한 AI 애플리케이션과 함께 사용할 수 있습니다:

• 클로드 데스크톱: 클로드용 앤트로픽의 데스크톱 애플리케이션
• 커서: 컴포저 기능에서 MCP를 지원하는 AI 기반 코드 편집기
• 기타 커스텀 MCP 클라이언트 MCP 클라이언트 사양을 구현하는 모든 애플리케이션

Claude Desktop에서 MCP 사용

1. Claude Desktop을 설치합니다.
2. Claude 구성 파일을 엽니다:
   • macOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json
3. 다음 구성을 추가합니다:

{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://localhost:19530"
      ]
    }
  }
}

4. Claude Desktop을 재시작하여 변경 사항을 적용합니다.

Cursor에서 MCP 사용

Cursor는 Composer의 에이전트 기능을 통해 MCP 도구도 지원합니다. 두 가지 방법으로 Milvus MCP 서버를 Cursor에 추가할 수 있습니다:

옵션 1: 커서 설정 UI 사용

1. Cursor Settings → Features → MCP 을 엽니다.
2. + Add New MCP Server 을 클릭합니다.
3. 입력합니다:
   • 유형: stdio
   • 이름: milvus
   • Command:

     /PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530
     

   • ⚠️ 팁: 잠재적인 DNS 확인 문제를 방지하려면 localhost 대신 127.0.0.1 을 사용하세요.

옵션 2: 프로젝트별 구성 사용(권장)

1. 프로젝트 루트 디렉터리에 .cursor/mcp.json 파일을 만듭니다:

{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://127.0.0.1:19530"
      ]
    }
  }
}

2. 커서를 다시 시작하여 구성을 적용합니다.

서버를 추가한 후 MCP 설정에서 새로 고침 버튼을 눌러 도구 목록을 채워야 할 수 있습니다. 컴포저 에이전트는 쿼리와 관련된 경우 자동으로 Milvus 도구를 사용합니다.

연동 확인

MCP 서버가 올바르게 설정되었는지 확인합니다:

커서의 경우

1. Cursor Settings → Features → MCP 로 이동합니다.
2. MCP 서버 목록에 "Milvus" 이 표시되는지 확인합니다.
3. Milvus 도구(예: milvus_list_collections, milvus_vector_search)가 나열되어 있는지 확인합니다.
4. 오류가 나타나면 아래의 문제 해결 섹션을 참조하세요.

Milvus용 MCP 서버 도구

이 MCP 서버는 Milvus에서 벡터 데이터를 검색, 쿼리 및 관리하기 위한 여러 도구를 제공합니다. 자세한 내용은 mcp-server-milvus 문서를 참조하세요.

🔍 검색 및 쿼리 도구

• milvus-text-search → 전체 텍스트 검색으로 문서를 검색합니다.
• milvus-vector-search → 컬렉션에서 벡터 유사도 검색을 수행합니다.
• milvus-hybrid-search → 벡터 유사도 검색과 속성 필터링을 결합한 하이브리드 검색을 수행합니다.
• milvus-multi-vector-search → 여러 쿼리 벡터로 벡터 유사도 검색 수행하기.
• milvus-query → 필터 표현식을 사용하여 컬렉션 쿼리하기.
• milvus-count → 컬렉션의 엔티티 개수 계산하기.

📁 컬렉션 관리

• milvus-list-collections → 데이터베이스에 있는 모든 컬렉션을 나열합니다.
• milvus-collection-info → 컬렉션에 대한 상세 정보를 조회합니다.
• milvus-get-collection-stats → 컬렉션에 대한 통계 가져오기.
• milvus-create-collection → 지정된 스키마로 새 컬렉션 만들기.
• milvus-load-collection → 검색 및 쿼리를 위해 컬렉션을 메모리에 로드합니다.
• milvus-release-collection → 메모리에서 컬렉션 해제하기.
• milvus-get-query-segment-info → 쿼리 세그먼트에 대한 정보 조회하기.
• milvus-get-collection-loading-progress → 컬렉션의 로딩 진행률 조회하기.

📊 데이터 작업

• milvus-insert-data → 컬렉션에 데이터를 삽입합니다.
• milvus-bulk-insert → 성능 향상을 위해 데이터를 일괄적으로 삽입합니다.
• milvus-upsert-data → 컬렉션에 데이터를 삽입합니다(있는 경우 삽입 또는 업데이트).
• milvus-delete-entities → 필터 표현식에 따라 컬렉션에서 엔티티를 삭제합니다.
• milvus-create-dynamic-field → 기존 컬렉션에 동적 필드를 추가합니다.

⚙️ 인덱스 관리

• milvus-create-index → 벡터 필드에 인덱스를 생성합니다.
• milvus-get-index-info → 컬렉션의 인덱스에 대한 정보를 가져옵니다.

환경 변수

• MILVUS_URI → Milvus 서버 URI( --milvus-uri 대신 설정 가능).
• MILVUS_TOKEN → 인증 토큰(선택 사항).
• MILVUS_DB → 데이터베이스 이름(기본값은 "기본값").

개발

서버를 직접 실행합니다:

uv run server.py --milvus-uri http://localhost:19530

예시

Claude 데스크톱 사용

예제 1: 컬렉션 나열하기

What are the collections I have in my Milvus DB?

그런 다음 Claude는 MCP를 사용하여 Milvus DB에서 이 정보를 확인합니다.

I'll check what collections are available in your Milvus database.

> View result from milvus-list-collections from milvus (local)

Here are the collections in your Milvus database:

1. rag_demo
2. test
3. chat_messages
4. text_collection
5. image_collection
6. customized_setup
7. streaming_rag_demo

예 2: 문서 검색

Find documents in my text_collection that mention "machine learning"

Claude는 Milvus의 전체 텍스트 검색 기능을 사용하여 관련 문서를 찾습니다:

I'll search for documents about machine learning in your text_collection.

> View result from milvus-text-search from milvus (local)

Here are the documents I found that mention machine learning:
[Results will appear here based on your actual data]

커서 사용

예시: 컬렉션 만들기

커서의 작곡기에서 요청할 수 있습니다:

Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)

커서는 MCP 서버를 사용하여 이 작업을 실행합니다:

I'll create a new collection called 'articles' with the specified fields.

> View result from milvus-create-collection from milvus (local)

Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float vector[128]

문제 해결

일반적인 문제

연결 오류

"Milvus 서버에 연결하지 못했습니다"와 같은 오류가 표시되는 경우:

1. Milvus 인스턴스가 실행 중인지 확인합니다: docker ps (Docker를 사용하는 경우).
2. 구성에서 URI가 올바른지 확인합니다.
3. 연결을 차단하는 방화벽 규칙이 없는지 확인합니다.
4. URI에 localhost 대신 127.0.0.1 을 사용해보세요.

인증 문제

인증 오류가 표시되는 경우

1. MILVUS_TOKEN 이 올바른지 확인합니다.
2. Milvus 인스턴스에 인증이 필요한지 확인합니다.
3. 수행하려는 작업에 대한 올바른 권한이 있는지 확인합니다.

도구를 찾을 수 없음

MCP 도구가 클로드 데스크톱 또는 커서에 나타나지 않는 경우:

1. 애플리케이션을 다시 시작하세요.
2. 서버 로그에서 오류를 확인합니다.
3. MCP 서버가 올바르게 실행되고 있는지 확인합니다.
4. MCP 설정에서 새로고침 버튼을 누릅니다(커서의 경우).

도움말 받기

문제가 계속 발생하는 경우

1. 깃허브 이슈에서 비슷한 문제가 있는지 확인하세요.
2. 질리즈 커뮤니티 디스코드에 가입하여 지원 받기
3. 문제에 대한 자세한 정보와 함께 새 이슈를 제출하세요.

결론

이 튜토리얼을 따라하면 이제 밀버스에서 인공지능 기반 벡터 검색이 가능한 MCP 서버를 실행할 수 있습니다. 이제 클로드 데스크톱을 사용하든 커서를 사용하든 데이터베이스 코드를 작성하지 않고도 자연어 명령을사용하여 Milvus 데이터베이스를 쿼리, 관리 및 검색할 수 있습니다!