Qdrant MCP
oficialBusca 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
queryem linguagem natural comqdrant-find. - Escolher coleção — Defina uma
collection_nameespecífica por chamada ou configure um padrão usandoCOLLECTION_NAME. - Personalizar descrições das ferramentas — Adapte
TOOL_STORE_DESCRIPTIONeTOOL_FIND_DESCRIPTIONpara transformar o servidor em uma ferramenta de busca de trechos de código. - Modo somente leitura — Ative
QDRANT_READ_ONLYpara desabilitar o armazenamento e permitir apenas a recuperação. - Ajustar resultados — Limite os resultados da busca com
QDRANT_SEARCH_LIMITe escolha um modelo de embeddings usandoEMBEDDING_MODEL.
Documentação
mcp-server-qdrant: Um servidor MCP do Qdrant
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
qdrant-store- Armazena informações no banco de dados Qdrant
- Entrada:
information(string): Informações a armazenarmetadata(JSON): Metadados opcionais a armazenarcollection_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
qdrant-find- Recupera informações relevantes do banco de dados Qdrant
- Entrada:
query(string): Consulta a ser usada na buscacollection_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_URLeQDRANT_LOCAL_PATHao mesmo tempo.
| Nome | Descrição | Valor padrão |
|---|---|---|
QDRANT_URL | URL do servidor Qdrant | Nenhum |
QDRANT_API_KEY | Chave de API do 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" é compatível) | fastembed |
EMBEDDING_MODEL | Nome do modelo de embeddings a ser usado | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Descrição personalizada da ferramenta de armazenamento | Consulte o padrão em settings.py |
TOOL_FIND_DESCRIPTION | Descrição personalizada da ferramenta de busca | Consulte o padrão em settings.py |
QDRANT_SEARCH_LIMIT | Número máximo de resultados a retornar da busca | 10 |
QDRANT_READ_ONLY | Ativar 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 ambiente | Descrição | Valor padrão |
|---|---|---|
FASTMCP_LOG_LEVEL | Define o nível de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
FASTMCP_DEBUG | Ativa o modo de depuração | false |
FASTMCP_HOST | Endereço do host ao qual vincular o servidor (transportes SSE e HTTP) | 127.0.0.1 |
FASTMCP_PORT | Porta na qual executar o servidor (transportes SSE e HTTP) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | Oculta detalhes de exceções das mensagens de erro das ferramentas enviadas aos clientes | false |
[!NOTE] Antes da versão 0.9.0, essas configurações usavam o prefixo
FASTMCP_SERVER_, por exemplo,FASTMCP_SERVER_HOST. Os nomes antigosFASTMCP_SERVER_HOST,FASTMCP_SERVER_PORTeFASTMCP_SERVER_DEBUGainda 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 locaissse: Transporte Server-Sent Events, ideal para clientes remotosstreamable-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:
- 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 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
-
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 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:
- Usar a ferramenta
qdrant-storepara armazenar trechos de código com descrições. - Usar a ferramenta
qdrant-findpara 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:
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.