Skip to main content
Glama
deenesjakoruzh
michal7kw

qdrant-mcp-ollama

by michal7kw
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

qdrant-mcp-ollama

Model Context Protocol (MCP)을 위한 서버로, Qdrant 벡터 데이터베이스에 GPU 가속 임베딩을 제공하기 위해 Ollama를 사용합니다.

왜 공식 mcp-server-qdrant를 사용하지 않나요?

공식 Qdrant MCP server는 임베딩에 FastEmbed를 사용합니다. 그 결과는 다음과 같습니다:

  • CPU에서만 실행됩니다 — 대규모 코드베이스에서 느리고, 최신 GPU를 제대로 활용하지 못합니다

  • 작은 모델을 사용합니다 (all-MiniLM-L6-v2, 384차원) — 임베딩 품질이 낮습니다

  • 단일 프로세스 잠금 — 로컬 모드에서는 한 번에 하나의 MCP 클라이언트만 데이터베이스에 접근할 수 있습니다

이 서버는 세 가지 문제를 모두 해결합니다:

공식 mcp-server-qdrant

qdrant-mcp-ollama

임베딩 엔진

FastEmbed (CPU)

Ollama (GPU)

기본 모델

all-MiniLM-L6-v2 (384-dim, 80MB)

bge-m3 (1024-dim, 1.2GB)

동시 접근

불가 (로컬 모드)

가능 (Qdrant 서버)

모델 유연성

FastEmbed 모델만 지원

모든 Ollama 임베딩 모델 지원

Related MCP server: Claude Context MCP

아키텍처

┌──────────────┐     ┌────────────────────┐     ┌─────────────┐
│  MCP Client   │────>│  qdrant-mcp-ollama │────>│   Ollama    │
│ (Claude Code, │     │    (server.py)      │     │  (GPU)      │
│  Kilo Code,   │<────│                    │     └─────────────┘
│  Cursor, etc) │     └────────┬───────────┘
└──────────────┘              │
                              v
                   ┌────────────────────┐
                   │   Qdrant Server    │
                   │  (Docker, :6333)   │
                   │  Storage: local    │
                   │  disk / cloud      │
                   └────────────────────┘

사전 요구 사항

  • Ollama — 임베딩 모델을 다운로드하고 실행 중이어야 합니다

  • Docker — Qdrant 서버 실행용

  • uv — Python 패키지 매니저 (권장) 또는 pip

빠른 시작

1. Ollama에서 임베딩 모델 다운로드

ollama pull bge-m3

2. Qdrant 서버 시작

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

3. MCP 서버 실행

# No install needed — uv downloads dependencies on-the-fly:
QDRANT_URL="http://localhost:6333" \
EMBEDDING_MODEL="bge-m3" \
uv run --with fastmcp --with qdrant-client --with httpx python server.py

4. 코드베이스 임베딩

uv run --with qdrant-client --with httpx python embed_codebase.py \
  /path/to/your/project my-project --preset python

5. MCP 클라이언트에서 검색

설정이 완료되면(아래 섹션 참조) AI 어시스턴트에게 다음과 같이 요청하세요:

"코드베이스에서 인증 로직을 검색해 줘"

그러면 qdrant_find 도구를 사용하여 의미적으로 관련 있는 코드 조각을 반환합니다.

Qdrant 서버 설정

방법 A: Docker (권장)

특정 드라이브(예: Windows의 E:)에 데이터를 저장하세요:

# Create storage directories
mkdir -p E:/qdrant-storage E:/qdrant-snapshots

# Start Qdrant with persistent storage
docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v E:/qdrant-storage:/qdrant/storage \
  -v E:/qdrant-snapshots:/qdrant/snapshots \
  --restart unless-stopped \
  qdrant/qdrant:latest

Linux/macOS:

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v ~/qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

--restart unless-stopped 플래그는 Qdrant가 Docker Desktop과 함께 자동으로 시작되도록 합니다.

실행 중인지 확인하세요:

docker ps --filter name=qdrant-server
# Or open http://localhost:6333/dashboard in your browser

방법 B: Qdrant Cloud

cloud.qdrant.io에 가입하여 URL과 API key를 받으세요. 그런 다음 설정하세요:

QDRANT_URL="https://your-cluster.cloud.qdrant.io:6333"
QDRANT_API_KEY="your-api-key"

참고: QDRANT_API_KEY 환경 변수는 Qdrant 클라이언트에 자동으로 전달됩니다.

코드베이스 임베딩

embed_codebase.py 스크립트는 디렉토리를 스캔하고, 소스 파일을 청크로 나눈 다음, GPU에서 실행되는 Ollama를 사용하여 Qdrant에 일괄 임베딩합니다.

기본 사용법

uv run --with qdrant-client --with httpx python embed_codebase.py <directory> <collection-name>

확장자 프리셋 사용

# Python project
python embed_codebase.py ./my-api api-backend --preset python

# Full-stack web project
python embed_codebase.py ./my-app frontend --preset web

# R / bioinformatics project
python embed_codebase.py ./analysis bio-analysis --preset r

# Everything
python embed_codebase.py ./mono-repo all-code --preset all

사용자 정의 확장자

python embed_codebase.py ./project my-collection --extensions .py .sql .sh .yaml

사용 가능한 프리셋

프리셋

확장자

python

.py .pyi

javascript

.js .jsx .mjs .cjs

typescript

.ts .tsx

web

.js .jsx .ts .tsx .vue .svelte .html .css .scss

r

.R .r .Rmd .rmd

java

.java

csharp

.cs

go

.go

rust

.rs

cpp

.cpp .hpp .cc .hh .c .h

all

모든 일반적인 소스 확장자

--preset 또는 --extensions를 지정하지 않으면 스크립트가 파일 유형을 자동 감지합니다.

전체 옵션

usage: embed_codebase.py <directory> <collection> [options]

positional arguments:
  directory              Path to the codebase directory
  collection             Qdrant collection name

options:
  --extensions EXT [EXT ...]  File extensions to include (e.g. .py .ts)
  --preset PRESET             Use a preset group of extensions
  --model MODEL               Ollama embedding model (default: bge-m3)
  --qdrant-url URL            Qdrant server URL (default: http://localhost:6333)
  --ollama-url URL            Ollama server URL (default: http://localhost:11434)
  --chunk-size N              Max lines per chunk (default: 80)
  --chunk-overlap N           Overlap lines between chunks (default: 10)
  --batch-size N              Upload batch size for Qdrant (default: 500)
  --append                    Append to existing collection instead of replacing

Append 모드

기본적으로 스크립트를 다시 실행하면 컬렉션을 교체합니다. 기존 컬렉션에 항목을 추가하려면 --append를 사용하세요:

# First embed
python embed_codebase.py ./src main-code --preset typescript

# Add more files later
python embed_codebase.py ./docs main-code --extensions .md --append

멀티 코드베이스 사용

각 코드베이스별로 별도 컬렉션을 사용하면 검색 결과의 범위와 관련성을 유지할 수 있습니다:

# Project A
python embed_codebase.py ~/projects/api-server api-server --preset python

# Project B
python embed_codebase.py ~/projects/web-app web-app --preset web

# Project C
python embed_codebase.py ~/projects/data-pipeline data-pipeline --preset python

MCP 서버를 설정할 때:

  • COLLECTION_NAME 미설정: 쿼리마다 컬렉션을 직접 지정해야 합니다. 하나의 MCP 서버가 여러 프로젝트를 지원할 때 이상적입니다.

  • COLLECTION_NAME 설정: 기본 컬렉션이 자동으로 사용됩니다. MCP 클라이언트가 프로젝트 범위 구성을 지원하면 프로젝트별로 설정하세요.

Claude Code 설정

MCP 서버 추가

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

/path/to/qdrant-mcp-ollama/를 이 저장소를 클론한 실제 경로로 바꾸세요.

기본 컬렉션 사용

주로 한 프로젝트에서 작업한다면:

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -e COLLECTION_NAME="my-project" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

확인

claude mcp list
# Should show: qdrant: ... ✓ Connected

claude mcp get qdrant
# Shows full configuration details

Claude Code에서 사용

설정이 완료되면 Claude Code는 다음 도구를 사용할 수 있습니다:

  • qdrant_store — 정보 저장: "이 인증 패턴을 Qdrant에 저장하세요."

  • qdrant_find — 검색: "데이터베이스 마이그레이션과 관련된 코드를 찾아주세요."

멀티 컬렉션 설정(기본값 없음)에서는 컬렉션을 직접 지정하세요:

api-server 컬렉션에서 rate limiting 로직을 검색하세요

Kilo Code (VS Code 확장) 설정

Kilo Code는 MCP 지원이 내장된 VS Code 확장 프로그램입니다.

방법 1: 수동 MCP 구성

  1. VS Code에서 Kilo Code 설정을 엽니다.

  2. MCP Servers 구성으로 이동합니다.

  3. 새 서버를 추가합니다:

필드

값

이름

qdrant

명령어

uv

인수

run --with fastmcp --with qdrant-client --with httpx python /path/to/server.py

  1. 환경 변수를 설정합니다:

변수

값

QDRANT_URL

http://localhost:6333

OLLAMA_URL

http://localhost:11434

EMBEDDING_MODEL

bge-m3

COLLECTION_NAME

프로젝트 컬렉션 이름 (예: my-project)

방법 2: VS Code settings.json

VS Code의 settings.json에 추가하세요 (Ctrl+Shift+P > Preferences: Open User Settings (JSON)):

{
  "kilocode.mcpServers": {
    "qdrant": {
      "command": "uv",
      "args": [
        "run", "--with", "fastmcp", "--with", "qdrant-client", "--with", "httpx",
        "python", "/path/to/qdrant-mcp-ollama/server.py"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "bge-m3",
        "COLLECTION_NAME": "my-project"
      }
    }
  }
}

Kilo Code 프로젝트별 설정

멀티 코드베이스 설정에서는 Kilo Code를 전역이 아닌 프로젝트 범위에서 프로젝트별 COLLECTION_NAME으로 구성하세요. 이렇게 하면 각 작업공간이 자신의 코드베이스만 검색합니다.

다른 MCP 클라이언트 설정

Cursor / Windsurf

SSE 전송으로 서버를 실행하여 원격 기능을 지원하는 클라이언트에서 연결하세요:

QDRANT_URL="http://localhost:6333" \
OLLAMA_URL="http://localhost:11434" \
EMBEDDING_MODEL="bge-m3" \
FASTMCP_PORT=8000 \
uv run --with fastmcp --with qdrant-client --with httpx \
  python server.py --transport sse

그런 다음 Cursor/Windsurf MCP 설정에서 http://localhost:8000/sse에 연결합니다.

일반 MCP 클라이언트 (stdio)

기본 전송은 stdio입니다. MCP 클라이언트와 stdio를 지원하는 어떤 클라이언트든 다음 명령으로 이 서버를 사용할 수 있습니다:

uv run --with fastmcp --with qdrant-client --with httpx python server.py

설정 참조

MCP 서버 환경 변수

변수

설명

기본값

QDRANT_URL

Qdrant 서버 URL

http://localhost:6333

QDRANT_API_KEY

Qdrant Cloud용 API key

없음

OLLAMA_URL

Ollama 서버 URL

http://localhost:11434

EMBEDDING_MODEL

Ollama 임베딩 모델 이름

bge-m3

COLLECTION_NAME

기본 컬렉션 (비워두면 호출 시 항상 지정해야 함)

(비어 있음)

임베딩 모델 선택

아래 모든 모델은 ollama pull <model>로 사용할 수 있습니다:

모델

차원

크기

속도

품질

적합한 용도

bge-m3

1024

1.2 GB

보통

높음

범용, 다국어

nomic-embed-text

768

274 MB

빠름

좋음

가벼운 모델, 영어 중심

mxbai-embed-large

1024

670 MB

중간

높음

영어, 높은 품질

snowflake-arctic-embed2

1024

1.2 GB

중간

매우 높음

최고 품질, 영어

all-minilm

384

46 MB

매우 빠름

보통

최소 리소스

권장 사항: bge-m3로 시작하세요. 코드를 잘 처리하고, 다국어 콘텐츠(모든 언어의 주석)를 지원하며, 품질과 속도의 균형이 좋습니다.

중요: 컬렉션을 인덱싱할 때 사용하는 임베딩 모델은 쿼리할 때 사용하는 모델과 반드시 일치해야 합니다. 다른 모델로 다시 임베딩하려면 컬렉션을 삭제하고 다시 생성하세요.

GPU 활용

모델이 클수록 GPU를 더 많이 사용합니다. GPU 활용률이 낮을 때:

  • nomic-embed-text (274 MB) 에서 bge-m3 (1.2 GB) 또는 그 이상의 모델로 전환하세요.

  • 임베딩 스크립트는 모든 텍스트를 단일 배치로 전송하여 GPU 활용률을 극대화합니다.

  • 개별 쿼리(qdrant_find)의 경우 GPU 사용이 짧게 치솟는 것은 정상입니다. 단일 쿼리 임베딩은 수 밀리초 사이에 완료됩니다.

GPU 사용량 확인: nvidia-smi (NVIDIA) 또는 rocm-smi (AMD)

MCP 도구

qdrant_store

Qdrant 데이터베이스에 정보를 저장합니다.

매개변수

타입

필수

설명

information

string

예

저장하고 검색 가능하게 할 텍스트

collection_name

string

기본값 미설정 시

대상 컬렉션

metadata

dict

아니요

첨부할 선택적 메타데이터

qdrant_find

의미론적 유사성을 사용하여 관련 정보를 검색합니다.

매개변수

타입

필수

설명

query

string

예

자연어 검색 쿼리

collection_name

string

기본값 미설정 시

검색할 컬렉션

top_k

int

아니

반환할 최대 결과 수 (기본값: 5)

문제 해결

"연결이 종료됨" / MCP 서버가 시작되지 않음

  • Ollama가 실행 중인가요? ollama list로 확인하세요. 필요하다면 ollama serve로 시작하세요.

  • 임베딩 모델이 다운로드되어 있나요? ollama pull bge-m3를 실행하세요.

  • Qdrant가 실행 중인가요? docker ps --filter name=qdrant-server로 확인하세요.

"컬렉션이 존재하지 않습니다"

컬렉션은 임베딩 스크립트 또는 첫 번째 qdrant_store 호출 시 생성됩니다. 따라서:

  • 먼저 embed_codebase.py를 실행하여 코드베이스를 인덱싱하거나,

  • 컬렉션을 자동 생성하려면 qdrant_store로 정보를 저장하세요.

차원 불일치 오류

이 오류는 컬렉션을 생성할 때 사용한 임베딩 모델과 쿼리 시 사용하는 임베딩 모델이 다를 때 발생합니다. 해결 방법:

  1. 컬렉션을 삭제하세요: http://localhost:6333/dashboard 접속

  2. 올바른 모델로 다시 임베딩하세요.

  3. MCP 서버 구성의 EMBEDDING_MODEL이 임베딩에 사용한 모델과 일치하는지 확인하세요.

"저장 폴더가 다른 인스턴스에 의해 이미 접근되고 있습니다"

이 오류는 공식 mcp-server-qdrant가 로컬 모드(QDRANT_LOCAL_PATH)를 사용할 때 발생합니다. 이 프로젝트는 Qdrant 서버를 URL로 연결하여 이 오류를 피합니다. 두 서버가 동일한 로컬 경로를 사용하여 실행되지 않도록 하십시오.

임베딩 속도 저하 / GPU 활용도 낮음

  • 더 큰 모델 사용: bge-m3 (1.2 GB) 대신 nomic-embed-text (274 MB)

  • 임베딩 스크립트는 모든 텍스트를 한 번의 배치로 전송합니다 — 청크가 수천 개라면 GPU 사용률을 극대화합니다.

  • 매우 큰 코드베이스(10,000+개 파일)의 경우 디렉터리별로 여러 번에 나눠 실행하는 것을 고려하세요.

라이선스

Apache License 2.0 — LICENSE를 참조하세요.

Install Server
A
license - permissive license
B
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Hint-Services-obsidian-github-mcp

    Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…

  • Ragora

    Search your knowledge bases from any AI assistant using hybrid RAG.

  • Maguyva

    Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/michal7kw/qdrant-mcp-ollama'

If you have feedback or need assistance with the MCP directory API, please join our Discord server