Milvus MCP Server

oficial

Pesquise, consulte e interaja com dados no seu Milvus Vector Database.

GitHub
233

Documentação

Servidor MCP para Milvus

O Model Context Protocol (MCP) é um protocolo aberto que permite integração perfeita entre aplicações LLM e fontes de dados e ferramentas externas. Seja você um desenvolvedor criando uma IDE com IA, aprimorando uma interface de chat ou criando fluxos de trabalho de IA personalizados, o MCP fornece uma maneira padronizada de conectar LLMs ao contexto de que precisam.

Este repositório contém um servidor MCP que fornece acesso à funcionalidade do banco de dados vetorial Milvus.

MCP with Milvus

Pré-requisitos

Antes de usar este servidor MCP, certifique-se de ter:

  • Python 3.10 ou superior
  • Uma instância do Milvus em execução (local ou remota)
  • uv instalado (recomendado para executar o servidor)

Uso

A maneira recomendada de usar este servidor MCP é executá-lo diretamente com uv sem instalação. É assim que tanto o Claude Desktop quanto o Cursor são configurados para usá-lo nos exemplos abaixo.

Se você quiser clonar o repositório:

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

Então você pode executar o servidor diretamente:

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

Alternativamente, você pode alterar o arquivo .env no diretório src/mcp_server_milvus/ para definir as variáveis de ambiente e executar o servidor com o seguinte comando:

uv run src/mcp_server_milvus/server.py

Importante: o arquivo .env terá prioridade mais alta que os argumentos da linha de comando.

Modos de Execução

O servidor suporta dois modos de execução: stdio (padrão) e SSE (Server-Sent Events).

Modo Stdio (Padrão)

  • Descrição: Comunica-se com o cliente via entrada/saída padrão. Este é o modo padrão se nenhum modo for especificado.

  • Uso:

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

Modo SSE

  • Descrição: Usa HTTP Server-Sent Events para comunicação. Este modo permite que vários clientes se conectem via HTTP e é adequado para aplicações baseadas na web.

  • Uso:

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
    • --sse: Habilita o modo SSE.
    • --port: Especifica a porta para o servidor SSE (padrão: 8000).

  • Depuração no Modo SSE:

    Se você quiser depurar no modo SSE, após iniciar o serviço SSE, digite o seguinte comando:

    mcp dev src/mcp_server_milvus/server.py

    A saída será semelhante 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 🚀

    Você pode então acessar o MCP Inspector em http://127.0.0.1:6274 para testes.

Modo HTTP Transmissível

  • Descrição: Usa HTTP com suporte a streaming para comunicação. Este é o transporte recomendado para implantações em produção e suporta operação com e sem estado.

  • Uso:

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http: Habilita o modo HTTP Transmissível.
    • --port: Especifica a porta para o servidor (padrão: 8000).
    • --stateless: Sinalizador opcional para modo sem estado (sem persistência de sessão).

  • Modo Sem Estado:

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

Aplicações Suportadas

Este servidor MCP pode ser usado com várias aplicações LLM que suportam o Model Context Protocol:

  • Claude Desktop: Aplicação desktop da Anthropic para Claude
  • Cursor: Editor de código com IA e suporte a MCP
  • Clientes MCP personalizados: Qualquer aplicação que implemente a especificação do cliente MCP

Uso com Claude Desktop

Configuração para Diferentes Modos

Configuração do Modo SSE

Siga estas etapas para configurar o Claude Desktop para o modo SSE:

  1. Instale o Claude Desktop a partir de https://claude.ai/download.
  2. Abra seu arquivo de configuração do Claude Desktop:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Adicione a seguinte configuração para o modo SSE:
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuração do Modo HTTP Transmissível

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. Reinicie o Claude Desktop para aplicar as alterações.

Configuração do Modo Stdio

Para o modo stdio, siga estas etapas:

  1. Instale o Claude Desktop a partir de https://claude.ai/download.
  2. Abra seu arquivo de configuração do Claude Desktop:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Adicione a seguinte configuração para o 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"
      ]
    }
  }
}
  1. Reinicie o Claude Desktop para aplicar as alterações.

Uso com Cursor

O Cursor também suporta ferramentas MCP. Você pode integrar seu servidor MCP Milvus com o Cursor seguindo estas etapas:

Etapas de Integração

  1. Abra Cursor Settings > MCP
  2. Clique em Add new global MCP server
  3. Após clicar, você será redirecionado automaticamente para o arquivo mcp.json, que será criado se não existir

Configurando o Arquivo mcp.json

Para Modo Stdio:

Substitua o conteúdo do arquivo mcp.json pelo seguinte:

{
  "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 Modo SSE:

  1. Inicie o serviço executando o seguinte comando:

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

    Nota: Substitua http://your_sse_host pelo seu endereço de host SSE real e port pelo número da porta específica que você está usando.

  2. Quando o serviço estiver em execução, substitua o conteúdo do arquivo mcp.json pelo seguinte:

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

Para Modo HTTP Transmissível:

  1. Inicie o serviço:

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

  2. Atualize mcp.json:

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

Concluindo a Integração

Após concluir as etapas acima, reinicie o Cursor ou recarregue a janela para garantir que a configuração tenha efeito.

Verificando a Integração

Para verificar se o Cursor foi integrado com sucesso ao seu servidor MCP Milvus:

  1. Abra Cursor Settings > MCP
  2. Verifique se "milvus", "milvus-sse" ou "milvus-streamable-http" aparecem na lista (dependendo do modo que você escolheu)
  3. Confirme se as ferramentas relevantes estão listadas (por exemplo, milvus_list_collections, milvus_vector_search, etc.)
  4. Se o servidor estiver habilitado, mas mostrar um erro, verifique a seção de Solução de Problemas abaixo

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas:

Operações de Busca e Consulta

  • milvus_text_search: Buscar documentos usando busca de texto completo

    • Parâmetros:
      • collection_name: Nome da coleção a ser pesquisada
      • query_text: Texto a ser pesquisado
      • limit: Número máximo de resultados a retornar (padrão: 5)
      • output_fields: Campos a incluir nos resultados
      • drop_ratio: Proporção de termos de baixa frequência a ignorar (0.0-1.0) (padrão: 0.2)

  • milvus_vector_search: Realizar busca por similaridade vetorial em uma coleção

    • Parâmetros:
      • collection_name: Nome da coleção a ser pesquisada
      • vector: Vetor de consulta
      • vector_field: Nome do campo para busca vetorial (padrão: "vector")
      • limit: Número máximo de resultados a retornar (padrão: 5)
      • output_fields: Campos a incluir nos resultados
      • filter_expr: Expressão de filtro
      • metric_type: Métrica de distância (COSINE, L2, IP) (padrão: "COSINE")
      • radius: Limite inferior opcional para busca por intervalo (padrão: None)
      • range_filter: Limite superior opcional para busca por intervalo (padrão: None)

  • milvus_hybrid_search: Realizar busca híbrida em uma coleção

    • Parâmetros:
      • collection_name: Nome da coleção a ser pesquisada
      • query_text: Consulta de texto para busca
      • text_field: Nome do campo para busca de texto
      • vector: Vetor da consulta de texto
      • vector_field: Nome do campo para busca vetorial
      • limit: Número máximo de resultados a retornar (padrão: 5)
      • output_fields: Campos a incluir nos resultados
      • filter_expr: Expressão de filtro
      • sparse_radius: Limite inferior opcional para busca por intervalo esparso (padrão: None)
      • sparse_range_filter: Limite superior opcional para busca por intervalo esparso (padrão: None)
      • dense_radius: Limite inferior opcional para busca por intervalo denso (padrão: None)
      • dense_range_filter: Limite superior opcional para busca por intervalo denso (padrão: None)

  • milvus_text_similarity_search: Realizar busca por similaridade de texto em uma coleção

    Nota: Esta ferramenta só é suportada no Milvus 2.6.0 e superior. E você precisa definir a função de incorporação no servidor Milvus. Consulte Função de Incorporação para mais detalhes.

    • Parâmetros:
      • collection_name: Nome da coleção a ser pesquisada
      • query_text: Consulta de texto para busca por similaridade
      • anns_field: Nome do campo para busca de texto
      • limit: Número máximo de resultados a retornar (padrão: 5)
      • output_fields: Campos a incluir nos resultados
      • metric_type: Métrica de distância (COSINE, L2, IP) (padrão: "COSINE")
      • filter_expr: Expressão de filtro opcional
      • radius: Limite inferior opcional para busca por intervalo (padrão: None)
      • range_filter: Limite superior opcional para busca por intervalo (padrão: None)

  • milvus_query: Consultar coleção usando expressões de filtro

    • Parâmetros:
      • collection_name: Nome da coleção a ser consultada
      • filter_expr: Expressão de filtro (ex.: 'age > 20')
      • output_fields: Campos a incluir nos resultados
      • limit: Número máximo de resultados a retornar (padrão: 10)

Gerenciamento de Coleções

  • milvus_list_collections: Listar todas as coleções no banco de dados

  • milvus_create_collection: Criar uma nova coleção com configuração rápida ou esquema personalizado

    • Parâmetros:
      • collection_name: Nome para a nova coleção
      • auto_id: se deve gerar id automaticamente, padrão True
      • dimension: dimensão do vetor, padrão 768; para configuração rápida e será ignorado se field_schema for fornecido
      • primary_field_name: nome do campo primário, padrão "id"; para configuração rápida e será ignorado se field_schema for fornecido
      • vector_field_name: nome do campo vetorial, padrão "vector"; para configuração rápida e será ignorado se field_schema for fornecido
      • metric_type: tipo de métrica, padrão "COSINE"; para configuração rápida e será ignorado se field_schema for fornecido
      • field_schema: Lista de esquema de campos, cada elemento é um dicionário com as seguintes chaves:
        • name: nome do campo
        • type: tipo do campo
      • index_params: Lista opcional de parâmetros de índice, cada elemento é um dicionário com as seguintes chaves:
        • field_name: nome do campo a ser indexado
        • index_type: tipo de índice
        • **kwargs: outros parâmetros de índice opcionais
      • other_kwargs: Argumentos de palavra-chave adicionais para a criação da coleção

  • milvus_load_collection: Carregar uma coleção na memória para busca e consulta

    • Parâmetros:
      • collection_name: Nome da coleção a ser carregada
      • replica_number: Número de réplicas (padrão: 1)

  • milvus_release_collection: Liberar uma coleção da memória

    • Parâmetros:
      • collection_name: Nome da coleção a ser liberada

  • milvus_get_collection_info: Lista informações detalhadas como esquema, propriedades, ID da coleção e outros metadados de uma coleção específica.

    • Parâmetros:
      • collection_name: Nome da coleção para obter informações detalhadas

Operações de Dados

  • milvus_insert_data: Inserir dados em uma coleção

    • Parâmetros:
      • collection_name: Nome da coleção
      • data: Dicionário mapeando nomes de campos para listas de valores

  • milvus_delete_entities: Excluir entidades de uma coleção com base em expressão de filtro

    • Parâmetros:
      • collection_name: Nome da coleção
      • filter_expr: Expressão de filtro para selecionar entidades a serem excluídas

Variáveis de Ambiente

  • MILVUS_URI: URI do servidor Milvus (pode ser definido em vez de --milvus-uri)
  • MILVUS_TOKEN: Token de autenticação opcional
  • MILVUS_DB: Nome do banco de dados (padrão "default")

Desenvolvimento

Para executar o servidor diretamente:

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

Exemplos

Usando Claude Desktop

Exemplo 1: Listando Coleções

What are the collections I have in my Milvus DB?

O Claude usará então o MCP para verificar essas informações no seu banco de dados 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

Exemplo 2: Buscando Documentos

Find documents in my text_collection that mention "machine learning"

O Claude usará os recursos de busca de texto completo do 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

Exemplo: Criando uma Coleção

No Cursor, você pode perguntar:

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

O Cursor usará o servidor MCP para executar esta operação:

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]

Solução de Problemas

Problemas Comuns

Erros de Conexão

Se você vir erros como "Failed to connect to Milvus server":

  1. Verifique se sua instância do Milvus está em execução: docker ps (se estiver usando Docker)
  2. Confirme se a URI está correta na sua configuração
  3. Certifique-se de que não há regras de firewall bloqueando a conexão
  4. Tente usar 127.0.0.1 em vez de localhost na URI

Problemas de Autenticação

Se você encontrar erros de autenticação:

  1. Verifique se seu MILVUS_TOKEN está correto
  2. Confira se sua instância do Milvus requer autenticação
  3. Certifique-se de ter as permissões corretas para as operações que está tentando realizar

Ferramenta Não Encontrada

Se as ferramentas MCP não aparecerem no Claude Desktop ou no Cursor:

  1. Reinicie o aplicativo
  2. Verifique os logs do servidor em busca de erros
  3. Confirme se o servidor MCP está funcionando corretamente
  4. Pressione o botão de atualizar nas configurações do MCP (no Cursor)

Obtendo Ajuda

Se você continuar enfrentando problemas:

  1. Consulte as Issues do GitHub para problemas semelhantes
  2. Entre no Discord da Comunidade Milvus para obter suporte
  3. Registre uma nova issue com informações detalhadas sobre o seu problema