MCP-сервер для Milvus

Name: MCP Server for Milvus
Author: zilliztech

Model Context Protocol (MCP) — это открытый протокол, который обеспечивает бесшовную интеграцию между приложениями LLM и внешними источниками данных и инструментами. Независимо от того, создаете ли вы IDE на базе ИИ, улучшаете интерфейс чата или создаете собственные рабочие процессы ИИ, MCP предоставляет стандартизированный способ подключения LLM к необходимому им контексту.

Этот репозиторий содержит сервер MCP, который обеспечивает доступ к функциональным возможностям векторной базы данных Milvus .

MCP с Milvus

Предпосылки

Перед использованием этого сервера MCP убедитесь, что у вас есть:

Python 3.10 или выше
Работающий экземпляр Milvus (локальный или удаленный)
uv установлен (рекомендуется для запуска сервера)

Related MCP server: Aiven MCP Server

Использование

Рекомендуемый способ использования этого сервера MCP — запустить его напрямую с uv без установки. Вот как Claude Desktop и Cursor настроены для его использования в примерах ниже.

Если вы хотите клонировать репозиторий:

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

В качестве альтернативы вы можете изменить файл .env в каталоге src/mcp_server_milvus/ чтобы задать переменные среды и запустить сервер с помощью следующей команды:

uv run src/mcp_server_milvus/server.py

Важно: файл .env будет иметь более высокий приоритет, чем аргументы командной строки.

Режимы работы

Сервер поддерживает два режима работы: stdio (по умолчанию) и SSE (Server-Sent Events).

Режим Stdio (по умолчанию)

Описание : Общается с клиентом через стандартный ввод/вывод. Это режим по умолчанию, если режим не указан.
Использование:
uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

Режим SSE

Описание : Использует HTTP Server-Sent Events для связи. Этот режим позволяет нескольким клиентам подключаться через HTTP и подходит для веб-приложений.
Использование:
uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
- --sse : Включает режим SSE.
- --port : Указывает порт для сервера SSE (по умолчанию: 8000).
Отладка в режиме SSE:
Если вы хотите выполнить отладку в режиме SSE, после запуска службы SSE введите следующую команду:
mcp dev src/mcp_server_milvus/server.py
Вывод будет примерно таким:
% mcp dev src/mcp_server_milvus/merged_server.py Starting MCP inspector... ⚙️ Proxy server listening on port 6277 🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
Затем вы можете получить доступ к MCP Inspector по адресу http://127.0.0.1:6274 для тестирования.

Поддерживаемые приложения

Этот сервер MCP можно использовать с различными приложениями LLM, которые поддерживают протокол контекста модели:

Claude Desktop : настольное приложение Anthropic для Claude
Курсор : редактор кода на базе искусственного интеллекта с поддержкой MCP
Пользовательские клиенты MCP : любое приложение, реализующее спецификацию клиента MCP.

Использование с Claude Desktop

Конфигурация для разных режимов

Конфигурация режима SSE

Чтобы настроить Claude Desktop для режима SSE, выполните следующие действия:

Установите Claude Desktop с https://claude.ai/download .
Откройте файл конфигурации Claude Desktop:
- macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Добавьте следующую конфигурацию для режима SSE:

{ "mcpServers": { "milvus-sse": { "url": "http://your_sse_host:port/sse", "disabled": false, "autoApprove": [] } } }

Перезапустите Claude Desktop, чтобы изменения вступили в силу.

Конфигурация режима stdio

Для режима stdio выполните следующие действия:

Установите Claude Desktop с https://claude.ai/download .
Откройте файл конфигурации Claude Desktop:
- macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Добавьте следующую конфигурацию для режима stdio:

{ "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, выполнив следующие шаги:

Этапы интеграции

Откройте Cursor Settings > MCP
Нажмите Add new global MCP server
После нажатия вы автоматически перейдете к файлу mcp.json , который будет создан, если его не существует.

Настройка файла `mcp.json`

Для стандартного режима:

Перезапишите файл mcp.json следующим содержимым:

Для режима SSE:

Запустите службу, выполнив следующую команду:
uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
Примечание : замените http://your_sse_host на фактический адрес вашего хоста SSE, а port на конкретный номер порта, который вы используете.
После запуска и запуска службы перезапишите файл mcp.json следующим содержимым:
{ "mcpServers": { "milvus-sse": { "url": "http://your_sse_host:port/sse", "disabled": false, "autoApprove": [] } } }

Завершение интеграции

После выполнения вышеуказанных шагов перезапустите Cursor или перезагрузите окно, чтобы убедиться, что конфигурация вступила в силу.

Проверка интеграции

Чтобы убедиться, что Cursor успешно интегрировался с вашим сервером Milvus MCP:

Откройте Cursor Settings > MCP
Проверьте, есть ли в списке «milvus» или «milvus-sse» (в зависимости от выбранного вами режима)
Убедитесь, что соответствующие инструменты перечислены (например, 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 : Поля для включения в результаты
  - filter_expr : Выражение фильтра
  - metric_type : Метрика расстояния (КОСИНУС, L2, IP) (по умолчанию: «КОСИНУС»)
milvus_hybrid_search : Выполнить гибридный поиск по коллекции
- Параметры:
  - collection_name : Название коллекции для поиска
  - query_text : Текстовый запрос для поиска
  - text_field : Имя поля для текстового поиска
  - vector : Вектор текстового запроса
  - vector_field : Имя поля для поиска вектора
  - limit : максимальное количество возвращаемых результатов
  - output_fields : Поля для включения в результаты
  - filter_expr : Выражение фильтра
milvus_query : Запрос коллекции с использованием выражений фильтра
- Параметры:
  - collection_name : Имя коллекции для запроса
  - filter_expr : Выражение фильтра (например, «возраст > 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_get_collection_info : выводит подробную информацию, такую как схема, свойства, идентификатор коллекции и другие метаданные конкретной коллекции.
- Параметры:
  - collection_name : Название коллекции, о которой нужно получить подробную информацию

Операции с данными

milvus_insert_data : вставить данные в коллекцию.
- Параметры:
  - collection_name : Название коллекции
  - data : Словарь, сопоставляющий имена полей со списками значений
milvus_delete_entities : Удаление сущностей из коллекции на основе выражения фильтра
- Параметры:
  - collection_name : Название коллекции
  - filter_expr : Выражение фильтра для выбора объектов для удаления

Переменные среды

MILVUS_URI : URI сервера Milvus (можно установить вместо --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?

Затем Клод проверит эту информацию в вашей базе данных Milvus с помощью MCP.

I'll check what collections are available in your Milvus database. 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"

Клод будет использовать возможности полнотекстового поиска 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 в вашей конфигурации.
Убедитесь, что нет правил брандмауэра, блокирующих соединение.
Попробуйте использовать 127.0.0.1 вместо localhost в URI

Проблемы с аутентификацией

Если вы видите ошибки аутентификации:

Проверьте правильность MILVUS_TOKEN
Проверьте, требует ли ваш экземпляр Milvus аутентификации.
Убедитесь, что у вас есть необходимые разрешения для операций, которые вы пытаетесь выполнить.

Инструмент не найден

Если инструменты MCP не отображаются в Claude Desktop или Cursor:

Перезапустите приложение.
Проверьте журналы сервера на наличие ошибок.
Убедитесь, что сервер MCP работает правильно.
Нажмите кнопку обновления в настройках MCP (для курсора)

Получение помощи

Если проблемы продолжаются:

Проверьте GitHub Issues на предмет похожих проблем.
Присоединяйтесь к сообществу Zilliz в Discord для получения поддержки
Создайте новый вопрос с подробной информацией о вашей проблеме