Milvus

Servidor MCP para Milvus

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

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

Requisitos previos

Antes de usar este servidor MCP, asegúrate 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 instalación. Así es como tanto Claude Desktop como Cursor están configurados para usarlo en los ejemplos a continuación.

Si deseas 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, puedes cambiar el archivo .env en el directorio src/mcp_server_milvus/ para establecer 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 línea de comandos.

Modos de ejecución

El servidor soporta dos modos de ejecución: stdio (predeterminado) y SSE (Server-Sent Events).

Modo Stdio (Predeterminado)

• Descripción: Se comunica con el cliente a través de entrada/salida estándar. Este es el modo predeterminado si no se especifica ningún modo.

• Uso:

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

Modo SSE

• Descripción: Utiliza HTTP Server-Sent Events para la comunicación. Este modo permite que múltiples clientes se conecten a través de HTTP y es adecuado para aplicaciones basadas en web.

• Uso:

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

  • --sse: Habilita el modo SSE.
  • --port: Especifica el puerto para el servidor SSE (predeterminado: 8000).

• Depuración en modo SSE:

  Si deseas depurar en modo SSE, después de iniciar el servicio SSE, ingresa el siguiente comando:

  mcp dev src/mcp_server_milvus/server.py
  

  La salida será similar a:

  % 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 🚀
  

  Luego puedes acceder al Inspector MCP en http://127.0.0.1:6274 para realizar pruebas.

Modo HTTP Transmisible

• Descripción: Utiliza HTTP con soporte de transmisión para la comunicación. Este es el transporte recomendado para despliegues en producción y soporta operación con y sin estado.

• Uso:

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

  • --streamable-http: Habilita el modo HTTP Transmisible.
  • --port: Especifica el puerto para el servidor (predeterminado: 8000).
  • --stateless: Bandera opcional para el modo sin estado (sin persistencia de sesión).

• Modo sin estado:

  uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000
  

Aplicaciones soportadas

Este servidor MCP se puede usar con varias aplicaciones LLM que soportan el Protocolo de Contexto de Modelo:

• Claude Desktop: La aplicación de escritorio de Anthropic para Claude
• Cursor: Editor de código potenciado por IA con soporte MCP
• Clientes MCP personalizados: Cualquier aplicación que implemente la especificación del cliente MCP

Uso con Claude Desktop

Configuración para diferentes modos

Configuración del modo SSE

Sigue estos pasos para configurar Claude Desktop para el modo SSE:

1. Instala Claude Desktop desde https://claude.ai/download.
2. Abre tu archivo de configuración de Claude Desktop:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Agrega la siguiente configuración para el modo SSE:

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

Configuración del modo HTTP Transmisible

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

4. Reinicia Claude Desktop para aplicar los cambios.

Configuración del modo Stdio

Para el modo stdio, sigue estos pasos:

1. Instala Claude Desktop desde https://claude.ai/download.
2. Abre tu archivo de configuración de Claude Desktop:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Agrega la siguiente configuración para el modo 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"
      ]
    }
  }
}

4. Reinicia Claude Desktop para aplicar los cambios.

Uso con Cursor

Cursor también soporta herramientas MCP. Puedes integrar tu servidor MCP de Milvus con Cursor siguiendo estos pasos:

Pasos de integración

1. Abre Cursor Settings > MCP
2. Haz clic en Add new global MCP server
3. Después de hacer clic, te redirigirá automáticamente al archivo mcp.json, que se creará si no existe

Configurando el archivo mcp.json

Para el modo Stdio:

Sobrescribe el 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"
      ]
    }
  }
}

Para el modo SSE:

1. Inicia el servicio ejecutando el siguiente comando:

   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
   

   Nota: Reemplaza http://your_sse_host con tu dirección de host SSE real y port con el número de puerto específico que estés usando.

2. Una vez que el servicio esté en funcionamiento, sobrescribe el archivo mcp.json con el siguiente contenido:

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

Para el modo HTTP Transmisible:

1. Inicia el servicio:

   uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port
   

2. Actualiza mcp.json:

   {
     "mcpServers": {
       "milvus-streamable-http": {
         "url": "http://your_host:port/mcp",
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

Completando la integración

Después de completar los pasos anteriores, reinicia Cursor o recarga la ventana para asegurar que la configuración surta efecto.

Verificando la integración

Para verificar que Cursor se ha integrado exitosamente con tu servidor MCP de Milvus:

1. Abre Cursor Settings > MCP
2. Verifica si "milvus", "milvus-sse" o "milvus-streamable-http" aparecen en la lista (dependiendo del modo que hayas elegido)
3. Confirma que las herramientas relevantes estén listadas (ej., milvus_list_collections, milvus_vector_search, etc.)
4. Si el servidor está habilitado pero muestra un error, consulta la sección de Solución de problemas a continuación

Herramientas disponibles

El servidor proporciona las siguientes herramientas:

Operaciones de búsqueda y consulta

• milvus_text_search: Buscar documentos usando búsqueda de texto completo

  • Parámetros:
    • collection_name: Nombre de la colección a buscar
    • query_text: Texto a buscar
    • limit: El número máximo de resultados a devolver (predeterminado: 5)
    • output_fields: Campos a incluir en los resultados
    • drop_ratio: Proporción de términos de baja frecuencia a ignorar (0.0-1.0) (predeterminado: 0.2)

• milvus_vector_search: Realizar 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: Nombre del campo para la búsqueda vectorial (predeterminado: "vector")
    • limit: El número máximo de resultados a devolver (predeterminado: 5)
    • output_fields: Campos a incluir en los resultados
    • filter_expr: Expresión de filtro
    • metric_type: Métrica de distancia (COSINE, L2, IP) (predeterminado: "COSINE")
    • radius: Límite inferior opcional para búsqueda por rango (predeterminado: None)
    • range_filter: Límite superior opcional para búsqueda por rango (predeterminado: None)

• milvus_hybrid_search: Realizar búsqueda híbrida en una colección

  • Parámetros:
    • collection_name: Nombre de la colección a buscar
    • query_text: Consulta de texto para la búsqueda
    • text_field: Nombre del campo para la búsqueda de texto
    • vector: Vector de la consulta de texto
    • vector_field: Nombre del campo para la búsqueda vectorial
    • limit: El número máximo de resultados a devolver (predeterminado: 5)
    • output_fields: Campos a incluir en los resultados
    • filter_expr: Expresión de filtro
    • sparse_radius: Límite inferior opcional para búsqueda por rango disperso (predeterminado: None)
    • sparse_range_filter: Límite superior opcional para búsqueda por rango disperso (predeterminado: None)
    • dense_radius: Límite inferior opcional para búsqueda por rango denso (predeterminado: None)
    • dense_range_filter: Límite superior opcional para búsqueda por rango denso (predeterminado: None)

• milvus_text_similarity_search: Realizar búsqueda de similitud de texto en una colección

  Nota: Esta herramienta solo está soportada en Milvus 2.6.0 y superior. Y necesitas configurar la función de embedding en el servidor Milvus. Consulta Función de Embedding para más detalles.

  • Parámetros:
    • collection_name: Nombre de la colección a buscar
    • query_text: Consulta de texto para la búsqueda de similitud
    • anns_field: Nombre del campo para la búsqueda de texto
    • limit: El número máximo de resultados a devolver (predeterminado: 5)
    • output_fields: Campos a incluir en los resultados
    • metric_type: Métrica de distancia (COSINE, L2, IP) (predeterminado: "COSINE")
    • filter_expr: Expresión de filtro opcional
    • radius: Límite inferior opcional para búsqueda por rango (predeterminado: None)
    • range_filter: Límite superior opcional para búsqueda por rango (predeterminado: None)

• milvus_query: Consultar colección usando expresiones de filtro

  • Parámetros:
    • collection_name: Nombre de la colección a consultar
    • filter_expr: Expresión de filtro (ej. 'age > 20')
    • output_fields: Campos a incluir en los resultados
    • limit: El número máximo de resultados a devolver (predeterminado: 10)

Gestión de colecciones

• milvus_list_collections: Listar todas las colecciones en la base de datos

• milvus_create_collection: Crear una nueva colección con configuración rápida o esquema personalizado

  • Parámetros:
    • collection_name: Nombre para la nueva colección
    • auto_id: si se debe auto generar id, predeterminado a True
    • dimension: dimensión del vector, predeterminado a 768; para configuración rápida y se ignorará si se proporciona field_schema
    • primary_field_name: nombre del campo primario, predeterminado a "id"; para configuración rápida y se ignorará si se proporciona field_schema
    • vector_field_name: nombre del campo vectorial, predeterminado a "vector"; para configuración rápida y se ignorará si se proporciona field_schema
    • metric_type: tipo de métrica, predeterminado a "COSINE"; para configuración rápida y se ignorará si se proporciona field_schema
    • field_schema: Lista de esquema de campo, cada elemento es un diccionario con las siguientes claves:
      • name: nombre del campo
      • type: tipo del campo
    • index_params: Lista opcional de parámetros de índice, cada elemento es un diccionario con las siguientes claves:
      • field_name: nombre del campo a indexar
      • index_type: tipo de índice
      • **kwargs: otros parámetros de índice opcionales
    • other_kwargs: Argumentos de palabra clave adicionales para la creación de la colección

• milvus_load_collection: Cargar una colección en memoria para búsqueda y consulta

  • 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

• milvus_get_collection_info: Lista información detallada como esquema, propiedades, ID de colección y otros metadatos de una colección específica.

  • Parámetros:
    • collection_name: Nombre de la colección de la cual obtener información detallada

Operaciones de datos

• milvus_insert_data: Insertar datos en una colección

  • Parámetros:
    • collection_name: Nombre de la colección
    • data: Diccionario que mapea nombres de campo a listas de valores

• milvus_delete_entities: Eliminar entidades de una colección basado en 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 establecer en lugar de --milvus-uri)
• MILVUS_TOKEN: Token de autenticación opcional
• MILVUS_DB: Nombre de la base de datos (predeterminado a "default")

Desarrollo

Para ejecutar el servidor directamente:

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

Ejemplos

Usando Claude Desktop

Ejemplo 1: Listando colecciones

What are the collections I have in my Milvus DB?

Claude luego usará MCP para verificar esta información en tu base de datos Milvus.

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

Ejemplo 2: Buscando documentos

Find documents in my text_collection that mention "machine learning"

Claude usará 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 Cursor

Ejemplo: Creando 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)

Cursor usará 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 ves errores como "Failed to connect to Milvus server":

1. Verifique que su instancia de Milvus esté en ejecución: docker ps (si usa Docker)
2. Compruebe que la URI sea correcta en su configuración
3. Asegúrese de que no haya reglas de firewall bloqueando la conexión
4. Intente usar 127.0.0.1 en lugar de localhost en la URI

Problemas de autenticación

Si ve errores de autenticación:

1. Verifique que su MILVUS_TOKEN sea correcto
2. Compruebe si su instancia de Milvus requiere autenticación
3. 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:

1. Reinicie la aplicación
2. Revise los registros del servidor en busca de errores
3. Verifique que el servidor MCP esté funcionando correctamente
4. Presione el botón de actualizar en la configuración de MCP (para Cursor)

Obtener ayuda

Si continúa experimentando problemas:

1. Consulte los GitHub Issues para problemas similares
2. Únase al Discord de la comunidad Milvus para obtener soporte
3. Registre un nuevo issue con información detallada sobre su problema