MCP + Milvus: Ligar a IA às bases de dados vectoriais

Introdução

O Protocolo de contexto de modelo (MCP) é um protocolo aberto que permite que aplicativos de IA, como Claude e Cursor, interajam com fontes de dados e ferramentas externas sem problemas. Quer você esteja criando aplicativos de IA personalizados, integrando fluxos de trabalho de IA ou aprimorando interfaces de bate-papo, o MCP fornece uma maneira padronizada de conectar modelos de linguagem grandes (LLMs) com dados contextuais relevantes.

Este tutorial orienta você na configuração de um servidor MCP para o Milvus, permitindo que os aplicativos de IA executem pesquisas vetoriais, gerenciem coleções e recuperem dados usando comandos de linguagem natural - semescrever consultas de banco de dados personalizadas.

Pré-requisitos

Antes de configurar o servidor MCP, verifique se você tem:

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

Como começar

A forma recomendada de usar este servidor MCP é executá-lo diretamente com uv sem instalação. É assim que o Claude Desktop e o Cursor são configurados para o utilizar 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 pode executar o servidor diretamente:

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

Aplicações suportadas

Este servidor MCP pode ser utilizado com várias aplicações de IA que suportam o Protocolo de contexto de modelo, tais como:

• Claude Desktop: A aplicação de ambiente de trabalho do Anthropic para o Claude
• Cursor: Editor de código alimentado por IA com suporte MCP em seu recurso Composer
• Outros clientes MCP personalizados Qualquer aplicação que implemente a especificação de cliente MCP

Usando a MCP com o Claude Desktop

1. Instale o Claude Desktop.
2. Abra o arquivo de configuração do Claude:
   • No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Adicione a seguinte configuração:

{
  "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. Reinicie o Claude Desktop para aplicar as alterações.

Usando o MCP com o Cursor

O Cursor também oferece suporte a ferramentas MCP por meio do recurso Agente no Composer. Pode adicionar o servidor Milvus MCP ao Cursor de duas formas:

Opção 1: Utilizar a IU de definições do Cursor

1. Abra Cursor Settings → Features → MCP.
2. Clique em + Add New MCP Server.
3. Preencha:
   • Type (Tipo): stdio
   • Nome: 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
     

   • ⚠️ Dica: Use 127.0.0.1 em vez de localhost para evitar possíveis problemas de resolução de DNS.

Opção 2: Usar a configuração específica do projeto (recomendado)

1. Crie um ficheiro .cursor/mcp.json no diretório raiz do seu projeto:

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

2. Reinicie o Cursor para aplicar a configuração.

Após adicionar o servidor, pode ser necessário pressionar o botão atualizar nas configurações do MCP para preencher a lista de ferramentas. O Agente de composição utilizará automaticamente as ferramentas Milvus quando for relevante para as suas consultas.

Verificação da integração

Para garantir que o servidor MCP está corretamente configurado:

Para o Cursor

1. Aceda a Cursor Settings → Features → MCP.
2. Confirmar que "Milvus" aparece na lista dos servidores CIM.
3. Verificar se as ferramentas Milvus (por exemplo, milvus_list_collections, milvus_vector_search) estão listadas.
4. Se aparecerem erros, consulte a secção Resolução de problemas abaixo.

Ferramentas do servidor MCP para Milvus

Este servidor MCP fornece várias ferramentas para pesquisar, consultar e gerir dados vectoriais em Milvus. Para obter mais detalhes, consulte a documentação do mcp-server-milvus.

🔍 Ferramentas de pesquisa e consulta

• milvus-text-search → Pesquisa de documentos utilizando a pesquisa de texto completo.
• milvus-vector-search → Realizar pesquisa de similaridade de vetores em uma coleção.
• milvus-hybrid-search → Efetuar uma pesquisa híbrida que combine a similaridade vetorial e a filtragem de atributos.
• milvus-multi-vector-search → Realizar pesquisa de similaridade vetorial com múltiplos vetores de consulta.
• milvus-query → Consulta de colecções utilizando expressões de filtragem.
• milvus-count → Contar entidades em uma coleção.

📁 Gestão de colecções

• milvus-list-collections → Listar todas as colecções na base de dados.
• milvus-collection-info → Obter informação detalhada sobre uma coleção.
• milvus-get-collection-stats → Obter estatísticas sobre uma coleção.
• milvus-create-collection → Criar uma nova coleção com o esquema especificado.
• milvus-load-collection → Carregar uma coleção na memória para pesquisa e consulta.
• milvus-release-collection → Libertar uma coleção da memória.
• milvus-get-query-segment-info → Obter informação sobre segmentos de consulta.
• milvus-get-collection-loading-progress → Obter o progresso do carregamento de uma coleção.

📊 Operações de Dados

• milvus-insert-data → Inserir dados numa coleção.
• milvus-bulk-insert → Inserir dados em lotes para um melhor desempenho.
• milvus-upsert-data → Inserir dados numa coleção (inserir ou atualizar se existir).
• milvus-delete-entities → Eliminar entidades de uma coleção com base numa expressão de filtro.
• milvus-create-dynamic-field → Adicionar um campo dinâmico a uma coleção existente.

⚙️ Gestão de índices

• milvus-create-index → Criar um índice sobre um campo vetorial.
• milvus-get-index-info → Obter informações sobre índices em uma coleção.

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 da base de dados (a predefinição é "default").

Desenvolvimento

Para executar o servidor diretamente:

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

Exemplos

Usando o Claude Desktop

Exemplo 1: Listagem de colecções

What are the collections I have in my Milvus DB?

O Claude irá então usar o MCP para verificar esta informação na nossa base de dados Milvus.

I'll check what collections are available in your Milvus database.

> View result from milvus-list-collections from milvus (local)

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: Pesquisa de documentos

Find documents in my text_collection that mention "machine learning"

O Claude utilizará as capacidades de pesquisa de texto integral 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]

Utilizar o Cursor

Exemplo: Criar uma coleção

No Compositor do Cursor, 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 irá utilizar o servidor MCP para executar esta operação:

I'll create a new collection called 'articles' with the specified fields.

> View result from milvus-create-collection from milvus (local)

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

Resolução de problemas

Problemas comuns

Erros de ligação

Se você vir erros como "Falha ao conectar ao servidor Milvus":

1. Verifique se a sua instância do Milvus está em execução: docker ps (se estiver a utilizar o Docker)
2. Verifique se o URI está correto na sua configuração
3. Certifique-se de que não existem regras de firewall a bloquear a ligação
4. Tente usar 127.0.0.1 em vez de localhost no URI

Problemas de autenticação

Se você vir erros de autenticação:

1. Verifique se o seu MILVUS_TOKEN está correto
2. Verifique se a sua instância Milvus requer autenticação
3. Certifique-se de que tem as permissões corretas para as operações que está a tentar executar

Ferramenta não encontrada

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

1. Reinicie a aplicação
2. Verifique se há erros nos logs do servidor
3. Verifique se o servidor MCP está sendo executado corretamente
4. Pressione o botão de atualização nas configurações do MCP (para o Cursor)

Obter ajuda

Se você continuar a ter problemas:

1. Verifique os Problemas do GitHub para problemas semelhantes
2. Junte-se ao Discord da Comunidade Zilliz para obter suporte
3. Arquivar um novo problema com informações detalhadas sobre o seu problema

Conclusão

Ao seguir este tutorial, tem agora um servidor MCP em execução, permitindo a pesquisa vetorial alimentada por IA em Milvus. Quer esteja a utilizar o Claude Desktop ou o Cursor, pode agora consultar, gerir e pesquisar a sua base de dados Milvus utilizando comandos de linguagem natural - semescrever código de base de dados!