Qdrant MCP

oficial

Busca semântica usando o banco de dados vetorial Qdrant.

O que você pode fazer com Qdrant MCP?

  • Armazenar memórias — Peça ao seu assistente para salvar informações, com metadados opcionais, em uma coleção do Qdrant usando qdrant-store.
  • Busca semântica — Recupere informações armazenadas relevantes usando uma query em linguagem natural com qdrant-find.
  • Escolher coleção — Defina uma collection_name específica por chamada ou configure um padrão usando COLLECTION_NAME.
  • Personalizar descrições das ferramentas — Adapte TOOL_STORE_DESCRIPTION e TOOL_FIND_DESCRIPTION para transformar o servidor em uma ferramenta de busca de trechos de código.
  • Modo somente leitura — Ative QDRANT_READ_ONLY para desabilitar o armazenamento e permitir apenas a recuperação.
  • Ajustar resultados — Limite os resultados da busca com QDRANT_SEARCH_LIMIT e escolha um modelo de embeddings usando EMBEDDING_MODEL.

Documentação

mcp-server-qdrant: Um servidor MCP do Qdrant

smithery badge

O Model Context Protocol (MCP) é um protocolo aberto que permite a integração perfeita entre aplicativos de LLM e fontes de dados e ferramentas externas. Seja para criar um IDE com tecnologia de IA, aprimorar uma interface de chat ou criar fluxos de trabalho personalizados com IA, o MCP oferece uma maneira padronizada de conectar LLMs ao contexto de que precisam.

Este repositório é um exemplo de como criar um servidor MCP para Qdrant, um mecanismo de busca vetorial.

Visão geral

Um servidor oficial do Model Context Protocol para armazenar e recuperar memórias no mecanismo de busca vetorial Qdrant. Ele funciona como uma camada de memória semântica sobre o banco de dados Qdrant.

Componentes

Ferramentas

  1. qdrant-store
    • Armazena informações no banco de dados Qdrant
    • Entrada:
      • information (string): Informações a armazenar
      • metadata (JSON): Metadados opcionais a armazenar
      • collection_name (string): Nome da coleção na qual armazenar as informações. Este campo é obrigatório se não houver um nome de coleção padrão. Se houver um nome de coleção padrão, este campo não estará habilitado.
    • Retorna: Mensagem de confirmação
  2. qdrant-find
    • Recupera informações relevantes do banco de dados Qdrant
    • Entrada:
      • query (string): Consulta a ser usada na busca
      • collection_name (string): Nome da coleção na qual armazenar as informações. Este campo é obrigatório se não houver um nome de coleção padrão. Se houver um nome de coleção padrão, este campo não estará habilitado.
    • Retorna: Informações armazenadas no banco de dados Qdrant como mensagens separadas

Variáveis de ambiente

A configuração é feita por meio de variáveis de ambiente. O único argumento de linha de comando é --transport, usado para selecionar o protocolo de transporte.

[!NOTE] Não é possível fornecer QDRANT_URL e QDRANT_LOCAL_PATH ao mesmo tempo.

NomeDescriçãoValor padrão
QDRANT_URLURL do servidor QdrantNenhum
QDRANT_API_KEYChave de API do servidor QdrantNenhum
COLLECTION_NAMENome da coleção padrão a ser usada.Nenhum
QDRANT_LOCAL_PATHCaminho para o banco de dados Qdrant local (alternativa a QDRANT_URL)Nenhum
EMBEDDING_PROVIDERProvedor de embeddings a ser usado (atualmente, apenas "fastembed" é compatível)fastembed
EMBEDDING_MODELNome do modelo de embeddings a ser usadosentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTIONDescrição personalizada da ferramenta de armazenamentoConsulte o padrão em settings.py
TOOL_FIND_DESCRIPTIONDescrição personalizada da ferramenta de buscaConsulte o padrão em settings.py
QDRANT_SEARCH_LIMITNúmero máximo de resultados a retornar da busca10
QDRANT_READ_ONLYAtivar modo somente leitura (desativa a ferramenta qdrant-store)false

Variáveis de ambiente do FastMCP

Como mcp-server-qdrant é baseado no FastMCP, ele também é compatível com todas as variáveis de ambiente do FastMCP. As mais importantes estão listadas abaixo:

Variável de ambienteDescriçãoValor padrão
FASTMCP_LOG_LEVELDefine o nível de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)INFO
FASTMCP_DEBUGAtiva o modo de depuraçãofalse
FASTMCP_HOSTEndereço do host ao qual vincular o servidor (transportes SSE e HTTP)127.0.0.1
FASTMCP_PORTPorta na qual executar o servidor (transportes SSE e HTTP)8000
FASTMCP_MASK_ERROR_DETAILSOculta detalhes de exceções das mensagens de erro das ferramentas enviadas aos clientesfalse

[!NOTE] Antes da versão 0.9.0, essas configurações usavam o prefixo FASTMCP_SERVER_, por exemplo, FASTMCP_SERVER_HOST. Os nomes antigos FASTMCP_SERVER_HOST, FASTMCP_SERVER_PORT e FASTMCP_SERVER_DEBUG ainda funcionam, mas estão obsoletos e serão removidos em uma versão futura. Se ambos os nomes estiverem definidos, o novo terá prioridade.

Instalação

Usando uvx

Ao usar uvx, não é necessária nenhuma instalação específica para executar diretamente o mcp-server-qdrant.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant

Protocolos de transporte

O servidor é compatível com diferentes protocolos de transporte, que podem ser especificados usando a flag --transport:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse

Protocolos de transporte compatíveis:

  • stdio (padrão): Transporte de entrada/saída padrão, que pode ser usado apenas por clientes MCP locais
  • sse: Transporte Server-Sent Events, ideal para clientes remotos
  • streamable-http: Transporte HTTP com streaming, ideal para clientes remotos e mais recente que SSE

O transporte padrão é stdio quando não especificado.

Quando o transporte SSE é usado, o servidor escuta na porta especificada e aguarda conexões de entrada. A porta padrão é 8000, mas pode ser alterada usando a variável de ambiente FASTMCP_PORT.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse

Usando Docker

Há um Dockerfile disponível para criar e executar o servidor MCP:

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_HOST="0.0.0.0" \
  -e QDRANT_URL="http://your-qdrant-server:6333" \
  -e QDRANT_API_KEY="your-api-key" \
  -e COLLECTION_NAME="your-collection" \
  mcp-server-qdrant

[!TIP] Observe que definimos FASTMCP_HOST="0.0.0.0" para que o servidor escute em todas as interfaces de rede. Isso é necessário ao executar o servidor em um contêiner Docker.

Instalação via Smithery

Para instalar automaticamente o Qdrant MCP Server para Claude Desktop via Smithery:

npx @smithery/cli install mcp-server-qdrant --client claude

Configuração manual do Claude Desktop

Para usar este servidor com o aplicativo Claude Desktop, adicione a configuração a seguir à seção "mcpServers" do seu claude_desktop_config.json:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
      "QDRANT_API_KEY": "your_api_key",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

Para o modo Qdrant local:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

Este servidor MCP criará automaticamente uma coleção com o nome especificado, caso ela não exista.

Por padrão, o servidor usará o modelo de embeddings sentence-transformers/all-MiniLM-L6-v2 para codificar memórias. Por enquanto, apenas modelos FastEmbed são compatíveis.

Compatibilidade com outras ferramentas

Este servidor MCP pode ser usado com qualquer cliente compatível com MCP. Por exemplo, você pode usá-lo com Cursor e VS Code, que oferecem suporte integrado ao Model Context Protocol.

Usando com Cursor/Windsurf

Você pode configurar este servidor MCP para funcionar como uma ferramenta de busca de código no Cursor ou Windsurf personalizando as descrições das ferramentas:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport

No Cursor/Windsurf, você pode configurar o servidor MCP nas configurações apontando para este servidor em execução usando o protocolo de transporte SSE. As instruções para adicionar um servidor MCP ao Cursor estão na documentação do Cursor. Se você estiver executando o Cursor/Windsurf localmente, poderá usar a seguinte URL:

http://localhost:8000/sse

[!TIP] Recomendamos o transporte SSE como forma preferencial de conectar o Cursor/Windsurf ao servidor MCP, pois ele permite conexões remotas. Isso facilita o compartilhamento do servidor com sua equipe ou o uso em um ambiente de nuvem.

Essa configuração transforma o servidor MCP do Qdrant em uma ferramenta especializada de busca de código que pode:

  1. Armazenar trechos de código, documentação e detalhes de implementação
  2. Recuperar exemplos de código relevantes com base em busca semântica
  3. Ajudar desenvolvedores a encontrar implementações ou padrões de uso específicos

Você pode preencher o banco de dados armazenando descrições em linguagem natural dos trechos de código (no parâmetro information) junto com o código correspondente (na propriedade metadata.code) e, em seguida, pesquisá-los usando consultas em linguagem natural que descrevam o que você está procurando.

[!NOTE] As descrições das ferramentas fornecidas acima são exemplos e talvez precisem ser personalizadas para seu caso de uso específico. Considere ajustá-las para corresponder melhor ao fluxo de trabalho da sua equipe e aos tipos específicos de trechos de código que você deseja armazenar e recuperar.

Se você instalou o mcp-server-qdrant com sucesso, mas ainda não consegue fazê-lo funcionar com o Cursor, considere criar as regras do Cursor para que as ferramentas MCP sejam sempre usadas quando o agente gerar um novo trecho de código. Você pode restringir as regras para que funcionem apenas com determinados tipos de arquivo, evitando o uso do servidor MCP para documentação ou outros tipos de conteúdo.

Usando com Claude Code

Você pode aprimorar os recursos do Claude Code conectando-o a este servidor MCP, habilitando a busca semântica na sua base de código existente.

Configurando o mcp-server-qdrant

  1. Adicione o servidor MCP ao Claude Code:

    # Add mcp-server-qdrant configured for code search
    claude mcp add code-search \
    -e QDRANT_URL="http://localhost:6333" \
    -e COLLECTION_NAME="code-repository" \
    -e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
    -e TOOL_STORE_DESCRIPTION="Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property." \
    -e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \
    -- uvx mcp-server-qdrant
    
  2. Verifique se o servidor foi adicionado:

    claude mcp list
    

Usando a busca semântica de código no Claude Code

As descrições das ferramentas, especificadas em TOOL_STORE_DESCRIPTION e TOOL_FIND_DESCRIPTION, orientam o Claude Code sobre como usar o servidor MCP. As descrições fornecidas acima são exemplos e talvez precisem ser personalizadas para seu caso de uso específico. No entanto, o Claude Code já deve ser capaz de:

  1. Usar a ferramenta qdrant-store para armazenar trechos de código com descrições.
  2. Usar a ferramenta qdrant-find para buscar trechos de código relevantes usando linguagem natural.

Executar o servidor MCP no modo de desenvolvimento

O servidor MCP pode ser executado no modo de desenvolvimento usando o comando mcp dev. Isso iniciará o servidor e abrirá o inspetor MCP no navegador.

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

Usando com VS Code

Para instalar com um clique, clique em um dos botões de instalação abaixo:

Install with UVX in VS Code Install with UVX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

Instalação manual

Adicione o seguinte bloco JSON ao arquivo User Settings (JSON) no VS Code. Para isso, pressione Ctrl + Shift + P e digite Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "uvx",
        "args": ["mcp-server-qdrant"],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

Ou, se preferir usar Docker, adicione esta configuração:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "docker",
        "args": [
          "run",
          "-p", "8000:8000",
          "-i",
          "--rm",
          "-e", "QDRANT_URL",
          "-e", "QDRANT_API_KEY",
          "-e", "COLLECTION_NAME",
          "mcp-server-qdrant"
        ],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

Como alternativa, você pode criar um arquivo .vscode/mcp.json no seu espaço de trabalho com o seguinte conteúdo:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Para configurar o espaço de trabalho com Docker, use isto em .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "docker",
      "args": [
        "run",
        "-p", "8000:8000",
        "-i",
        "--rm",
        "-e", "QDRANT_URL",
        "-e", "QDRANT_API_KEY",
        "-e", "COLLECTION_NAME",
        "mcp-server-qdrant"
      ],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Contribuição

Se você tiver sugestões para melhorar o mcp-server-qdrant ou quiser relatar um bug, abra uma issue! Toda e qualquer contribuição é muito bem-vinda.

Testando mcp-server-qdrant localmente

O inspetor MCP é uma ferramenta para desenvolvedores testarem e depurarem servidores MCP. Ele executa uma interface de cliente (porta padrão 5173) e um servidor proxy MCP (porta padrão 3000). Abra a interface do cliente no navegador para usar o inspetor.

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

Depois de iniciado, acesse http://localhost:5173 no navegador para abrir a interface do inspetor.

Licença

Este servidor MCP está licenciado sob a Apache License 2.0. Isso significa que você pode usar, modificar e distribuir o software, sujeito aos termos e condições da Apache License 2.0. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.

Privacidade e suporte