mcp-server-qdrant: Qdrant MCP 서버

모델 컨텍스트 프로토콜(MCP) 은 LLM 애플리케이션과 외부 데이터 소스 및 도구 간의 원활한 통합을 지원하는 개방형 프로토콜입니다. AI 기반 IDE를 구축하거나, 채팅 인터페이스를 개선하거나, 맞춤형 AI 워크플로를 만드는 경우, MCP는 LLM을 필요한 컨텍스트에 연결하는 표준화된 방법을 제공합니다.

이 저장소는 벡터 검색 엔진인 Qdrant를 위한 MCP 서버를 만드는 방법의 예입니다.

개요

Qdrant 벡터 검색 엔진에서 메모리를 보관하고 검색하는 공식 모델 컨텍스트 프로토콜 서버입니다. Qdrant 데이터베이스 위에서 의미론적 메모리 계층 역할을 합니다.

구성 요소

도구

qdrant-store
- Qdrant 데이터베이스에 일부 정보를 저장합니다.
- 입력:
  - information (문자열): 저장할 정보
  - metadata (JSON): 저장할 선택적 메타데이터
  - collection_name (문자열): 정보를 저장할 컬렉션의 이름입니다. 기본 컬렉션 이름이 없는 경우 이 필드는 필수입니다. 기본 컬렉션 이름이 있는 경우 이 필드는 활성화되지 않습니다.
- 반환: 확인 메시지
qdrant-find
- Qdrant 데이터베이스에서 관련 정보를 검색합니다.
- 입력:
  - query (문자열): 검색에 사용할 쿼리
  - collection_name (문자열): 정보를 저장할 컬렉션의 이름입니다. 기본 컬렉션 이름이 없는 경우 이 필드는 필수입니다. 기본 컬렉션 이름이 있는 경우 이 필드는 활성화되지 않습니다.
- 반환: Qdrant 데이터베이스에 별도의 메시지로 저장된 정보

환경 변수

서버 구성은 환경 변수를 사용하여 수행됩니다.

이름	설명	기본값
`QDRANT_URL`	Qdrant 서버의 URL	없음
`QDRANT_API_KEY`	Qdrant 서버용 API 키	없음
`COLLECTION_NAME`	사용할 기본 컬렉션의 이름입니다.	없음
`QDRANT_LOCAL_PATH`	로컬 Qdrant 데이터베이스 경로( `QDRANT_URL` 의 대안)	없음
`EMBEDDING_PROVIDER`	사용할 임베딩 제공자(현재 "fastembed"만 지원됨)	`fastembed`
`EMBEDDING_MODEL`	사용할 임베딩 모델의 이름	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	스토어 도구에 대한 사용자 정의 설명	`settings.py` 에서 기본값을 확인하세요
`TOOL_FIND_DESCRIPTION`	찾기 도구에 대한 사용자 정의 설명	`settings.py` 에서 기본값을 확인하세요

참고: QDRANT_URL 과 QDRANT_LOCAL_PATH 동시에 제공할 수 없습니다.

[!중요] 명령줄 인수는 더 이상 지원되지 않습니다! 모든 구성에 환경 변수를 사용하세요.

설치

uvx 사용

uvx 사용하면 mcp-server-qdrant를 직접 실행하기 위해 특별한 설치가 필요하지 않습니다.

지엑스피1

전송 프로토콜

서버는 --transport 플래그를 사용하여 지정할 수 있는 다양한 전송 프로토콜을 지원합니다.

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

지원되는 전송 프로토콜:

stdio (기본값): 표준 입출력 전송, 로컬 MCP 클라이언트에서만 사용될 수 있음
sse : 원격 클라이언트에 적합한 Server-Sent Events 전송

지정하지 않으면 기본 전송은 stdio 입니다.

Docker 사용

MCP 서버를 빌드하고 실행하려면 Dockerfile을 사용할 수 있습니다.

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

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

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Qdrant MCP 서버를 자동으로 설치하려면:

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

Claude Desktop 수동 구성

Claude Desktop 앱과 함께 이 서버를 사용하려면 claude_desktop_config.json 의 "mcpServers" 섹션에 다음 구성을 추가하세요.

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

로컬 Qdrant 모드의 경우:

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

이 MCP 서버는 지정된 이름의 컬렉션이 존재하지 않으면 자동으로 해당 컬렉션을 생성합니다.

기본적으로 서버는 sentence-transformers/all-MiniLM-L6-v2 임베딩 모델을 사용하여 메모리를 인코딩합니다. 현재로서는 FastEmbed 모델만 지원됩니다.

다른 도구에 대한 지원

이 MCP 서버는 모든 MCP 호환 클라이언트와 함께 사용할 수 있습니다. 예를 들어, 모델 컨텍스트 프로토콜(Model Context Protocol)을 기본적으로 지원하는 Cursor 및 VS Code 와 함께 사용할 수 있습니다.

커서/윈드서프와 함께 사용

다음과 같이 도구 설명을 사용자 정의하여 Cursor 또는 Windsurf의 코드 검색 도구로 작동하도록 이 MCP 서버를 구성할 수 있습니다.

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

Cursor/Windsurf에서는 SSE 전송 프로토콜을 사용하여 실행 중인 서버를 지정하여 설정에서 MCP 서버를 구성할 수 있습니다. Cursor에 MCP 서버를 추가하는 방법에 대한 설명은 Cursor 설명서 에서 확인할 수 있습니다. Cursor/Windsurf를 로컬에서 실행 중인 경우 다음 URL을 사용할 수 있습니다.

http://localhost:8000/sse

[!TIP] Cursor/Windsurf를 MCP 서버에 연결하는 가장 좋은 방법으로는 SSE 전송을 사용하는 것이 좋습니다. 원격 연결을 지원할 수 있기 때문입니다. SSE 전송을 사용하면 팀과 서버를 쉽게 공유하거나 클라우드 환경에서 사용할 수 있습니다.

이 구성을 사용하면 Qdrant MCP 서버가 다음을 수행할 수 있는 특수 코드 검색 도구로 변환됩니다.

코드 조각, 문서 및 구현 세부 정보 저장
의미 검색을 기반으로 관련 코드 예제를 검색합니다.
개발자가 특정 구현이나 사용 패턴을 찾도록 돕습니다.

실제 코드( metadata.code 속성)와 함께 코드 조각에 대한 자연어 설명( information 매개변수)을 저장하여 데이터베이스를 채운 다음, 원하는 내용을 설명하는 자연어 쿼리를 사용하여 해당 설명을 검색할 수 있습니다.

[!NOTE] 위에 제공된 도구 설명은 예시이며, 특정 사용 사례에 맞게 수정해야 할 수 있습니다. 팀의 워크플로와 저장 및 검색하려는 특정 유형의 코드 스니펫에 더 잘 맞도록 설명을 조정하는 것이 좋습니다.

mcp-server-qdrant 를 성공적으로 설치했지만 커서와 함께 사용할 수 없는 경우, 에이전트가 새 코드 조각을 생성할 때 MCP 도구가 항상 사용되도록 커서 규칙을 만들어 보세요. 특정 파일 형식에만 적용되도록 규칙을 제한하여 문서나 기타 유형의 콘텐츠에 MCP 서버를 사용하지 않도록 할 수 있습니다.

Claude Code와 함께 사용

Claude Code를 이 MCP 서버에 연결하여 기존 코드베이스에 대한 의미 검색을 활성화하면 Claude Code의 기능을 향상시킬 수 있습니다.

mcp-server-qdrant 설정

Claude Code에 MCP 서버를 추가합니다.
# 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
서버가 추가되었는지 확인하세요.
claude mcp list

Claude Code에서 의미 코드 검색 사용

TOOL_STORE_DESCRIPTION 과 TOOL_FIND_DESCRIPTION 에 지정된 도구 설명은 Claude Code에게 MCP 서버 사용 방법을 안내합니다. 위에 제공된 설명은 예시이며, 특정 사용 사례에 맞게 사용자 지정해야 할 수 있습니다. 하지만 Claude Code는 다음 작업을 수행할 수 있어야 합니다.

qdrant-store 도구를 사용하여 설명과 함께 코드 조각을 저장합니다.
qdrant-find 도구를 사용하면 자연어를 사용하여 관련 코드 조각을 검색합니다.

개발 모드에서 MCP 서버 실행

MCP 서버는 mcp dev 명령을 사용하여 개발 모드로 실행할 수 있습니다. 이렇게 하면 서버가 시작되고 브라우저에 MCP 검사기가 열립니다.

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

VS Code와 함께 사용

한 번의 클릭으로 설치하려면 아래 설치 버튼 중 하나를 클릭하세요.

수동 설치

VS Code의 사용자 설정(JSON) 파일에 다음 JSON 블록을 추가합니다. Ctrl + Shift + P 를 누르고 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}"
        }
      }
    }
  }
}

또는 Docker를 사용하는 것을 선호하는 경우 대신 다음 구성을 추가하세요.

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

또는 다음 내용이 포함된 .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": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Docker를 사용하여 작업 공간을 구성하려면 .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}"
      }
    }
  }
}

기여하다

mcp-server-qdrant 개선 방안에 대한 제안이 있거나 버그를 보고하고 싶으시면 이슈를 개설해 주세요! 모든 참여를 환영합니다.

로컬에서 `mcp-server-qdrant` 테스트

MCP 검사기는 MCP 서버를 테스트하고 디버깅하는 개발자 도구입니다. 클라이언트 UI(기본 포트 5173)와 MCP 프록시 서버(기본 포트 3000)를 모두 실행합니다. 검사기를 사용하려면 브라우저에서 클라이언트 UI를 여세요.

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

시작하면 브라우저를 http://localhost:5173 으로 열어 검사기 인터페이스에 접근합니다.

특허

이 MCP 서버는 Apache 라이선스 2.0에 따라 라이선스가 부여됩니다. 즉, Apache 라이선스 2.0의 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.

mcp-server-qdrant

mcp-server-qdrant: Qdrant MCP 서버

개요

구성 요소

도구

환경 변수

설치

uvx 사용

전송 프로토콜

Docker 사용

Smithery를 통해 설치

Claude Desktop 수동 구성

다른 도구에 대한 지원

커서/윈드서프와 함께 사용

Claude Code와 함께 사용

mcp-server-qdrant 설정

Claude Code에서 의미 코드 검색 사용

개발 모드에서 MCP 서버 실행

VS Code와 함께 사용

수동 설치

기여하다

로컬에서 `mcp-server-qdrant` 테스트

특허

Tools

Appeared in Searches

mcp-server-qdrant: Qdrant MCP 서버

개요

구성 요소

도구

환경 변수

설치

uvx 사용

전송 프로토콜

Docker 사용

Smithery를 통해 설치

Claude Desktop 수동 구성

다른 도구에 대한 지원

커서/윈드서프와 함께 사용

Claude Code와 함께 사용

mcp-server-qdrant 설정

Claude Code에서 의미 코드 검색 사용

개발 모드에서 MCP 서버 실행

VS Code와 함께 사용

수동 설치

기여하다

로컬에서 mcp-server-qdrant 테스트

특허

Tools

Appeared in Searches

로컬에서 `mcp-server-qdrant` 테스트