mcp-server-milvus 프로젝트 상세 소개

프로젝트 개요

mcp-server-milvus는 Zilliz Tech에서 개발한 오픈 소스 프로젝트로, Milvus 벡터 데이터베이스에 대한 Model Context Protocol (MCP) 서버 구현을 제공합니다. 이 프로젝트를 통해 LLM 애플리케이션은 표준화된 프로토콜을 통해 Milvus 벡터 데이터베이스의 기능을 원활하게 통합하고 액세스할 수 있습니다.

핵심 기능 특성

지원하는 작업 도구

이 MCP 서버는 다음과 같은 핵심 도구를 제공합니다.

• milvus_text_search: 전체 텍스트 검색 기능을 사용하여 문서 검색

  • 매개변수: collection_name, query_text, limit, output_fields, drop_ratio

• milvus_vector_search: 컬렉션에서 벡터 유사성 검색 실행

  • 매개변수: collection_name, vector, vector_field, limit, output_fields, metric_type

• milvus_query: 필터 표현식을 사용하여 컬렉션 쿼리

  • 매개변수: collection_name, filter_expr, output_fields, limit

• milvus_list_collections: 데이터베이스의 모든 컬렉션 나열

• milvus_create_collection: 지정된 스키마로 새 컬렉션 생성

  • 매개변수: collection_name, collection_schema, index_params

• milvus_load_collection: 검색 및 쿼리를 위해 컬렉션을 메모리에 로드

  • 매개변수: collection_name, replica_number

• milvus_release_collection: 메모리에서 컬렉션 해제

  • 매개변수: collection_name

• milvus_insert_data: 컬렉션에 데이터 삽입

  • 매개변수: collection_name, data

• milvus_delete_entities: 필터 표현식을 기반으로 컬렉션에서 엔터티 삭제

  • 매개변수: collection_name, filter_expr

시스템 요구 사항

• Python 3.10 이상
• 실행 중인 Milvus 인스턴스 (로컬 또는 원격)
• uv 도구 (서버 실행에 권장)

설치 및 구성

프로젝트 복제

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

서버 직접 실행

uv를 사용하여 서버를 직접 실행하는 것이 권장되며, 설치가 필요하지 않습니다.

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

또는 .env 파일에서 환경 변수를 설정하여 실행할 수 있습니다.

uv run src/mcp_server_milvus/server.py

지원하는 클라이언트 애플리케이션

이 MCP 서버는 Model Context Protocol을 지원하는 다양한 LLM 애플리케이션과 함께 사용할 수 있습니다.

Claude Desktop 통합

1. Claude Desktop 설치
2. claude_desktop_config.json 파일 구성:

{
  "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"
      ]
    }
  }
}

Cursor 편집기 통합

Cursor는 두 가지 구성 방식을 지원합니다.

방식 1: GUI를 통한 구성

1. Cursor Settings > Features > MCP로 이동
2. "+ Add New MCP Server" 버튼 클릭
3. 양식 작성:
   • Type: stdio 선택
   • Name: 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

방식 2: 구성 파일

.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"
      ]
    }
  }
}

환경 변수 구성

• MILVUS_URI: Milvus 서버 URI (--milvus-uri 매개변수 대체 가능)
• MILVUS_TOKEN: 선택적 인증 토큰
• MILVUS_DB: 데이터베이스 이름 (기본값: "default")

사용 예시

Claude Desktop에서의 사용

사용자는 자연어를 통해 Milvus 데이터베이스와 상호 작용할 수 있습니다.

컬렉션 목록 쿼리:

What are the collections I have in my Milvus DB?

문서 검색:

Find documents in my text_collection that mention "machine learning"

Cursor에서의 사용

새 컬렉션 생성:

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

문제 해결

연결 문제

• Milvus 인스턴스가 실행 중인지 확인
• URI 구성이 올바른지 확인
• 방화벽 규칙이 연결을 차단하지 않는지 확인
• localhost 대신 127.0.0.1 사용 시도

인증 문제

• MILVUS_TOKEN이 올바른지 확인
• Milvus 인스턴스에 인증이 필요한지 확인
• 작업을 수행할 수 있는 올바른 권한이 있는지 확인

기술 아키텍처

이 프로젝트는 Python을 기반으로 개발되었으며, 현대적인 개발 도구 체인을 사용합니다.

• uv를 패키지 관리 및 실행 도구로 사용
• MCP 표준 프로토콜 사양 준수
• 완전한 Milvus 데이터베이스 작업 래핑 제공
• 다양한 AI 애플리케이션 클라이언트 지원

응용 시나리오

이 프로젝트는 주로 다음과 같은 시나리오에 적합합니다.

• AI 기반 코드 편집기 향상
• 채팅 인터페이스의 컨텍스트 향상
• 사용자 정의 AI 워크플로 구축
• 벡터 데이터베이스와 LLM의 통합
• 의미 검색 및 RAG (검색 증강 생성) 응용

mcp-server-milvus를 통해 개발자는 Milvus 벡터 데이터베이스의 강력한 기능을 다양한 AI 애플리케이션에 쉽게 통합하여 사용자에게 더욱 지능적이고 정확한 상호 작용 경험을 제공할 수 있습니다.