Milvus용 MCP 서버

모델 컨텍스트 프로토콜(MCP)은 LLM 애플리케이션과 외부 데이터 소스 및 도구 간의 원활한 통합을 지원하는 개방형 프로토콜입니다. AI 기반 IDE를 구축하거나, 채팅 인터페이스를 개선하거나, 맞춤형 AI 워크플로를 만드는 경우, MCP는 LLM을 필요한 컨텍스트에 연결하는 표준화된 방법을 제공합니다.

이 저장소에는 Milvus 벡터 데이터베이스 기능에 대한 액세스를 제공하는 MCP 서버가 포함되어 있습니다.

필수 조건

이 MCP 서버를 사용하기 전에 다음 사항이 있는지 확인하세요.

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

용법

이 MCP 서버를 사용하는 권장 방법은 설치 없이 uv 사용하여 직접 실행하는 것입니다. 아래 예시에서는 Claude Desktop과 Cursor가 이 방식으로 구성되어 있습니다.

저장소를 복제하려면 다음을 수행합니다.

지엑스피1

그러면 서버를 직접 실행할 수 있습니다.

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

또는 src/mcp_server_milvus/ 디렉토리에 있는 .env 파일을 변경하여 환경 변수를 설정하고 다음 명령으로 서버를 실행할 수 있습니다.

uv run src/mcp_server_milvus/server.py

중요: .env 파일은 명령줄 인수보다 우선순위가 높습니다.

지원되는 애플리케이션

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

Claude Desktop : Claude를 위한 Anthropic의 데스크톱 애플리케이션
커서 : MCP를 지원하는 AI 기반 코드 편집기
사용자 정의 MCP 클라이언트 : MCP 클라이언트 사양을 구현하는 모든 애플리케이션

Claude Desktop과 함께 사용

https://claude.ai/download 에서 Claude Desktop을 설치하세요
Claude Desktop 구성을 엽니다.
- macOS: ~/Library/Application Support/Claude/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"
      ]
    }
  }
}

Claude Desktop을 다시 시작하세요

커서를 사용한 사용

Cursor는 MCP 도구도 지원합니다 . Milvus MCP 서버를 Cursor에 추가하는 방법은 두 가지가 있습니다.

옵션 1: 커서 설정 UI 사용

Cursor Settings > Features > MCP 로 이동하세요.
+ Add New MCP Server 버튼을 클릭하세요
양식을 작성하세요:
- 유형 : Select stdio (명령을 실행하고 있으므로)
- 이름 : milvus
- 명령어 : /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: 프로젝트별 구성 사용(권장)

프로젝트 루트에 .cursor/mcp.json 파일을 만듭니다.

프로젝트 루트에 .cursor 디렉토리를 만듭니다.
mkdir -p /path/to/your/project/.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" ] } } }
커서를 다시 시작하거나 창을 다시 로드하세요

서버를 추가한 후 도구 목록을 채우려면 MCP 설정에서 새로 고침 버튼을 눌러야 할 수 있습니다. 상담원은 문의 사항과 관련된 경우 Milvus 도구를 자동으로 사용합니다.

통합 확인

Cursor가 Milvus MCP 서버와 성공적으로 통합되었는지 확인하려면:

커서 설정 > 기능 > MCP 열기
MCP 서버 목록에 "Milvus"가 나타나는지 확인하세요.
도구가 나열되어 있는지 확인하세요(예: milvus_list_collections, milvus_vector_search 등)
서버가 활성화되어 있지만 오류가 표시되는 경우 아래의 문제 해결 섹션을 확인하세요.

사용 가능한 도구

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

검색 및 쿼리 작업

milvus_text_search : 전체 텍스트 검색을 사용하여 문서 검색
- 매개변수:
  - collection_name : 검색할 컬렉션의 이름
  - query_text : 검색할 텍스트
  - limit : 최대 결과 수 (기본값: 5)
  - output_fields : 결과에 포함할 필드
  - drop_ratio : 무시할 저주파 항목의 비율(0.0-1.0)
milvus_vector_search : 컬렉션에 대한 벡터 유사성 검색을 수행합니다.
- 매개변수:
  - collection_name : 검색할 컬렉션의 이름
  - vector : 쿼리 벡터
  - vector_field : 검색할 벡터를 포함하는 필드(기본값: "vector")
  - limit : 최대 결과 수 (기본값: 5)
  - output_fields : 결과에 포함할 필드
  - metric_type : 거리 측정법(코사인, L2, IP) (기본값: "코사인")
milvus_query : 필터 표현식을 사용한 쿼리 수집
- 매개변수:
  - collection_name : 쿼리할 컬렉션의 이름
  - filter_expr : 필터 표현식(예: 'age > 20')
  - output_fields : 결과에 포함할 필드
  - limit : 최대 결과 수 (기본값: 10)

컬렉션 관리

milvus_list_collections : 데이터베이스의 모든 컬렉션을 나열합니다.
milvus_create_collection : 지정된 스키마로 새 컬렉션을 만듭니다.
- 매개변수:
  - collection_name : 새 컬렉션의 이름
  - collection_schema : 컬렉션 스키마 정의
  - index_params : 선택적 인덱스 매개변수
milvus_load_collection : 검색 및 쿼리를 위해 컬렉션을 메모리에 로드합니다.
- 매개변수:
  - collection_name : 로드할 컬렉션의 이름
  - replica_number : 복제본 수 (기본값: 1)
milvus_release_collection : 메모리에서 컬렉션 해제
- 매개변수:
  - collection_name : 릴리스할 컬렉션의 이름

데이터 운영

milvus_insert_data : 컬렉션에 데이터 삽입
- 매개변수:
  - collection_name : 컬렉션의 이름
  - data : 필드 이름을 값 목록에 매핑하는 사전
milvus_delete_entities : 필터 표현식을 기반으로 컬렉션에서 엔터티 삭제
- 매개변수:
  - collection_name : 컬렉션의 이름
  - filter_expr : 삭제할 엔터티를 선택하는 필터 표현식

환경 변수

MILVUS_URI : Milvus 서버 URI(--milvus-uri 대신 설정 가능)
MILVUS_TOKEN : 선택적인 인증 토큰
MILVUS_DB : 데이터베이스 이름(기본값은 "default"입니다)

개발

서버를 직접 실행하려면:

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

예시

Claude Desktop 사용

예제 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.

Here are the collections in your Milvus database:

rag_demo
test
chat_messages
text_collection
image_collection
customized_setup
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.

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

문제 해결

일반적인 문제

연결 오류

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

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

인증 문제

인증 오류가 표시되는 경우:

MILVUS_TOKEN 이 정확한지 확인하세요
Milvus 인스턴스에 인증이 필요한지 확인하세요.
수행하려는 작업에 대한 올바른 권한이 있는지 확인하세요.

도구를 찾을 수 없습니다

MCP 도구가 Claude Desktop 또는 Cursor에 나타나지 않는 경우:

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

도움 받기

문제가 계속 발생하는 경우:

유사한 문제는 GitHub 이슈에서 확인하세요.
지원을 받으려면 Zilliz 커뮤니티 Discord에 가입하세요.
문제에 대한 자세한 정보와 함께 새로운 문제를 제출하세요.

MCP Server for Milvus

Integrations