Qdrant MCP Server

oficial

Implemente uma camada de memória semântica sobre o mecanismo de busca vetorial Qdrant

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. Seja você está construindo um 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 com o contexto de que precisam.

Este repositório é um exemplo de como criar um servidor MCP para o 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 ser armazenada
  - metadata (JSON): Metadados opcionais para armazenar
  - collection_name (string): Nome da coleção onde a informação será armazenada. 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 a busca
  - collection_name (string): Nome da coleção onde a informação será armazenada. 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 ambos 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 para `QDRANT_URL`)	Nenhum
`EMBEDDING_PROVIDER`	Provedor de embedding 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 serem retornados da busca	`10`
`QDRANT_READ_ONLY`	Habilita o modo somente leitura (desabilita 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 log (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Habilita o modo de depuração	`false`
`FASTMCP_SERVER_HOST`	Endereço do host ao qual o servidor será vinculado	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Porta na qual o servidor será executado	`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 a serem instaladas no ambiente do servidor	`[]`

[!NOTE] 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 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 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 de entrada/saída padrão, pode ser usado apenas por clientes MCP locais
sse: Transporte de Eventos Enviados pelo Servidor, 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 o 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. No momento, 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 para o Model Context Protocol.

Usando com Cursor/Windsurf

Você pode configurar este servidor MCP para funcionar como uma ferramenta de busca de código para o 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 em 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 a 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 seu 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) juntamente 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 funcionarem apenas para certos tipos de arquivo, para evitar o uso do servidor MCP para documentação ou outros tipos de conteúdo.

Usando com Claude Code

Você pode aprimorar as capacidades do Claude Code conectando-o a este servidor MCP, permitindo a busca semântica em 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 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 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 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:

{
  "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 isso no .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 sobre como o mcp-server-qdrant poderia ser melhorado, ou quiser relatar um bug, abra uma issue! Adoraríamos todas e quaisquer contribuições.

Testando o `mcp-server-qdrant` localmente

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

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

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

Licença

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