Servidor MCP para Milvus

El Protocolo de Contexto de Modelo (MCP) es un protocolo abierto que permite una integración fluida entre las aplicaciones LLM y las fuentes de datos y herramientas externas. Ya sea que esté creando un IDE basado en IA, mejorando una interfaz de chat o creando flujos de trabajo de IA personalizados, MCP proporciona una forma estandarizada de conectar las aplicaciones LLM con el contexto que necesitan.

Este repositorio contiene un servidor MCP que proporciona acceso a la funcionalidad de la base de datos de vectores de Milvus .

Prerrequisitos

Antes de utilizar este servidor MCP, asegúrese de tener:

Python 3.10 o superior
Una instancia de Milvus en ejecución (local o remota)
uv instalado (recomendado para ejecutar el servidor)

Uso

La forma recomendada de usar este servidor MCP es ejecutarlo directamente con uv sin necesidad de instalación. Así es como Claude Desktop y Cursor están configurados para usarlo en los ejemplos a continuación.

Si desea clonar el repositorio:

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

Luego puedes ejecutar el servidor directamente:

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

Alternativamente, puede cambiar el archivo .env en el directorio src/mcp_server_milvus/ para configurar las variables de entorno y ejecutar el servidor con el siguiente comando:

uv run src/mcp_server_milvus/server.py

Importante: el archivo .env tendrá mayor prioridad que los argumentos de la línea de comando.

Aplicaciones compatibles

Este servidor MCP se puede utilizar con varias aplicaciones LLM que admiten el Protocolo de contexto de modelo:

Claude Desktop : la aplicación de escritorio de Anthropic para Claude
Cursor : editor de código impulsado por IA con soporte MCP
Clientes MCP personalizados : cualquier aplicación que implemente la especificación del cliente MCP

Uso con Claude Desktop

Instale Claude Desktop desde https://claude.ai/download
Abra la configuración de Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Agregue la siguiente configuración:

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

Reiniciar Claude Desktop

Uso con cursor

Cursor también es compatible con herramientas MCP . Puede agregar el servidor Milvus MCP a Cursor de dos maneras:

Opción 1: Uso de la interfaz de configuración del cursor

Vaya a Cursor Settings > Features > MCP
Haga clic en el botón + Add New MCP Server
Rellene el formulario:
- Tipo : Seleccionar stdio (ya que estás ejecutando un comando)
- Nombre : milvus
- Comando : /PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530
⚠️ Nota: Utilice 127.0.0.1 en lugar de localhost para evitar posibles problemas de resolución de DNS.

Opción 2: Utilizar la configuración específica del proyecto (recomendado)

Cree un archivo .cursor/mcp.json en la raíz de su proyecto:

Crea el directorio .cursor en la raíz de tu proyecto:
mkdir -p /path/to/your/project/.cursor
Crea un archivo mcp.json con el siguiente contenido:
{ "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" ] } } }
Reiniciar el cursor o recargar la ventana

Después de agregar el servidor, es posible que deba presionar el botón de actualización en la configuración de MCP para completar la lista de herramientas. El agente usará automáticamente las herramientas de Milvus cuando sea relevante para sus consultas.

Verificando la integración

Para verificar que Cursor se haya integrado correctamente con su servidor Milvus MCP:

Abra Configuración del cursor > Funciones > MCP
Comprueba que "Milvus" aparece en la lista de servidores MCP
Verifique que las herramientas estén enumeradas (por ejemplo, milvus_list_collections, milvus_vector_search, etc.)
Si el servidor está habilitado pero muestra un error, consulte la sección Solución de problemas a continuación

Herramientas disponibles

El servidor proporciona las siguientes herramientas:

Operaciones de búsqueda y consulta

milvus_text_search : Busque documentos mediante la búsqueda de texto completo
- Parámetros:
  - collection_name : Nombre de la colección a buscar
  - query_text : Texto a buscar
  - limit : Máximo de resultados (predeterminado: 5)
  - output_fields : Campos a incluir en los resultados
  - drop_ratio : Proporción de términos de baja frecuencia que se deben ignorar (0,0-1,0)
milvus_vector_search : Realizar una búsqueda de similitud vectorial en una colección
- Parámetros:
  - collection_name : Nombre de la colección a buscar
  - vector : vector de consulta
  - vector_field : Campo que contiene los vectores a buscar (predeterminado: "vector")
  - limit : Máximo de resultados (predeterminado: 5)
  - output_fields : Campos a incluir en los resultados
  - metric_type : Métrica de distancia (COSINO, L2, IP) (predeterminado: "COSINO")
milvus_query : Colección de consultas mediante expresiones de filtro
- Parámetros:
  - collection_name : Nombre de la colección a consultar
  - filter_expr : expresión de filtro (por ejemplo, 'edad > 20')
  - output_fields : Campos a incluir en los resultados
  - limit : Máximo de resultados (predeterminado: 10)

Gestión de cobros

milvus_list_collections : Lista todas las colecciones en la base de datos
milvus_create_collection : Crea una nueva colección con el esquema especificado
- Parámetros:
  - collection_name : Nombre para la nueva colección
  - collection_schema : Definición del esquema de colección
  - index_params : Parámetros de índice opcionales
milvus_load_collection : Carga una colección en la memoria para realizar búsquedas y consultas.
- Parámetros:
  - collection_name : Nombre de la colección a cargar
  - replica_number : Número de réplicas (predeterminado: 1)
milvus_release_collection : Liberar una colección de la memoria
- Parámetros:
  - collection_name : Nombre de la colección a liberar

Operaciones de datos

milvus_insert_data : insertar datos en una colección
- Parámetros:
  - collection_name : Nombre de la colección
  - data : Diccionario que asigna nombres de campos a listas de valores
milvus_delete_entities : eliminar entidades de una colección según una expresión de filtro
- Parámetros:
  - collection_name : Nombre de la colección
  - filter_expr : Expresión de filtro para seleccionar entidades a eliminar

Variables de entorno

MILVUS_URI : URI del servidor Milvus (se puede configurar en lugar de --milvus-uri)
MILVUS_TOKEN : Token de autenticación opcional
MILVUS_DB : Nombre de la base de datos (predeterminado: "predeterminado")

Desarrollo

Para ejecutar el servidor directamente:

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

Ejemplos

Uso de Claude Desktop

Ejemplo 1: Listado de colecciones

What are the collections I have in my Milvus DB?

Luego, Claude utilizará MCP para verificar esta información en su base de datos Milvus.

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

Ejemplo 2: Búsqueda de documentos

Find documents in my text_collection that mention "machine learning"

Claude utilizará las capacidades de búsqueda de texto completo de Milvus para encontrar documentos relevantes:

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]

Usando el cursor

Ejemplo: Creación de una colección

En Cursor, puedes preguntar:

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

El cursor utilizará el servidor MCP para ejecutar esta operación:

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]

Solución de problemas

Problemas comunes

Errores de conexión

Si ve errores como "Error al conectarse al servidor Milvus":

Verifique que su instancia de Milvus se esté ejecutando: docker ps (si usa Docker)
Comprueba que la URI sea correcta en tu configuración
Asegúrese de que no haya reglas de firewall que bloqueen la conexión
Intente usar 127.0.0.1 en lugar de localhost en la URI

Problemas de autenticación

Si ve errores de autenticación:

Verifique que su MILVUS_TOKEN sea correcto
Comprueba si tu instancia de Milvus requiere autenticación
Asegúrese de tener los permisos correctos para las operaciones que intenta realizar

Herramienta no encontrada

Si las herramientas MCP no aparecen en Claude Desktop o Cursor:

Reiniciar la aplicación
Verifique los registros del servidor para detectar cualquier error
Verifique que el servidor MCP esté funcionando correctamente
Presione el botón de actualización en la configuración de MCP (para el cursor)

Obtener ayuda

Si continúa experimentando problemas:

Consulte los problemas de GitHub para ver problemas similares
Únete al Discord de la comunidad Zilliz para obtener ayuda.
Presentar un nuevo problema con información detallada sobre el mismo

MCP Server for Milvus

Integrations