Qdrant MCP

oficial

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

O que você pode fazer com Qdrant MCP?

Use o Qdrant como uma camada de memória semântica para seu assistente de IA, permitindo que ele armazene e recupere informações por significado, em vez de palavras-chave exatas.

Armazenar memórias semânticas — Peça ao seu assistente para salvar informações com metadados opcionais no Qdrant via qdrant-store para recuperação posterior.
Recuperar memórias relevantes — Use qdrant-find para pesquisar informações armazenadas com uma consulta em linguagem natural e obter resultados correspondentes.
Criar uma biblioteca de trechos de código — Armazene trechos de código com descrições e recupere-os semanticamente, como mostrado nas configurações do Cursor e do Claude Code.
Segmentar coleções específicas — Armazene ou pesquise em uma coleção nomeada via collection_name, ou use o padrão definido por COLLECTION_NAME.

Documentação

mcp-server-qdrant: Um servidor MCP Qdrant

O Model Context Protocol (MCP) é um protocolo aberto que permite integração perfeita entre aplicações LLM e fontes de dados e ferramentas externas. Esteja você construindo 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 é 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 atua como uma camada de memória semântica sobre o banco de dados Qdrant.

Componentes

Ferramentas

qdrant-store
- Armazena algumas informações no banco de dados Qdrant
- Entrada:
  - information (string): Informação a armazenar
  - metadata (JSON): Metadados opcionais para armazenar
  - collection_name (string): Nome da coleção para 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 é habilitado.
- Retorna: Mensagem de confirmação
qdrant-find
- Recupera informações relevantes do banco de dados Qdrant
- Entrada:
  - query (string): Consulta a ser usada para pesquisa
  - collection_name (string): Nome da coleção para 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 é 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] Você não pode fornecer QDRANT_URL e QDRANT_LOCAL_PATH ao mesmo tempo.

Nome	Descrição	Valor Padrão
`QDRANT_URL`	URL do servidor Qdrant	Nenhum
`QDRANT_API_KEY`	Chave de API para o servidor Qdrant	Nenhum
`COLLECTION_NAME`	Nome da coleção padrão a ser usada.	Nenhum
`QDRANT_LOCAL_PATH`	Caminho para o banco de dados Qdrant local (alternativa a `QDRANT_URL`)	Nenhum
`EMBEDDING_PROVIDER`	Provedor de embeddings a ser usado (atualmente apenas "fastembed" é suportado)	`fastembed`
`EMBEDDING_MODEL`	Nome do modelo de embedding a ser usado	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Descrição personalizada para a ferramenta de armazenamento	Veja o padrão em `settings.py`
`TOOL_FIND_DESCRIPTION`	Descrição personalizada para a ferramenta de busca	Veja o padrão em `settings.py`
`QDRANT_SEARCH_LIMIT`	Número máximo de resultados a retornar da pesquisa	`10`
`QDRANT_READ_ONLY`	Ativa o modo somente leitura (desativa a ferramenta `qdrant-store`)	`false`

Variáveis de Ambiente do FastMCP

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

Variável de Ambiente	Descrição	Valor Padrão
`FASTMCP_LOG_LEVEL`	Define o nível de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Ativa o modo de depuração	`false`
`FASTMCP_SERVER_HOST`	Endereço do host para vincular o servidor	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Porta para executar o servidor	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Comportamento para recursos duplicados (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Comportamento para ferramentas duplicadas (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Comportamento para prompts duplicados (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Lista de dependências para instalar no ambiente do servidor	`[]`

[!NOTE] As configurações específicas do servidor usam o prefixo FASTMCP_SERVER_. Isso pode mudar em versões futuras.

Instalação

Usando uvx

Ao usar uvx, nenhuma instalação específica é necessária para executar diretamente 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 suporta 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 suportados:

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

O transporte padrão é stdio se não for especificado.

Quando o transporte SSE é usado, o servidor escutará na porta especificada e aguardará conexões de entrada. A porta padrão é 8000, no entanto, ela pode ser alterada usando a variável de ambiente FASTMCP_SERVER_PORT.

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

Usando Docker

Um Dockerfile está disponível para construir e executar o servidor MCP:

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

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_SERVER_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_SERVER_HOST="0.0.0.0" para fazer o servidor escutar em todas as interfaces de rede. Isso é necessário ao executar o servidor em um contêiner Docker.

Instalando via Smithery

Para instalar o Qdrant MCP Server para Claude Desktop automaticamente 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 seguinte configuração à 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 se ela não existir.

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

Suporte para 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 fornecem 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 para 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 então configurar o servidor MCP nas suas configurações apontando para este servidor em execução usando o protocolo de transporte SSE. A descrição de como adicionar um servidor MCP ao Cursor pode ser encontrada na documentação do Cursor. Se você estiver executando o Cursor/Windsurf localmente, pode usar a seguinte URL:

http://localhost:8000/sse

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

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

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

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

[!NOTE] As descrições de ferramentas fornecidas acima são exemplos e podem precisar ser personalizadas para o seu caso de uso específico. Considere ajustar as descrições para melhor corresponder 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 com sucesso o mcp-server-qdrant, mas ainda não consegue fazê-lo funcionar com o Cursor, por favor considere criar as regras do Cursor para que as ferramentas MCP sejam sempre usadas quando o agente produzir um novo trecho de código. Você pode restringir as regras para funcionar apenas para determinados tipos de arquivo, para evitar usar o 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, permitindo busca semântica sobre sua base de código existente.

Configurando mcp-server-qdrant

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

Verifique se o servidor foi adicionado:
```
claude mcp list
```

Usando 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 fornecidas acima são exemplos e podem precisar ser personalizadas para o seu caso de uso específico. No entanto, o Claude Code já deve ser capaz de:

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

Executar o servidor MCP em Modo de Desenvolvimento

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

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

Usando com VS Code

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

Instalação Manual

Adicione o seguinte bloco JSON ao seu arquivo de Configurações do Usuário (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando 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 em vez disso:

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

Alternativamente, 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 configuração do 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}"
      }
    }
  }
}

Contribuindo

Se você tiver sugestões de como o mcp-server-qdrant pode ser melhorado, ou quiser relatar um bug, abra uma issue! Adoraríamos todas e quaisquer contribuições.

Testando `mcp-server-qdrant` localmente

O inspetor MCP é uma ferramenta de desenvolvedor para testar e depurar servidores MCP. Ele executa tanto uma interface de cliente (porta padrão 5173) quanto um servidor proxy MCP (porta padrão 3000). Abra a interface do cliente no seu navegador para usar o inspetor.

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

Depois de iniciado, abra seu navegador em http://localhost:5173 para acessar a interface do inspetor.

Licença

Este servidor MCP é licenciado sob a Apache License 2.0. Isso significa que você é livre para 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.