Skip to main content
Glama
deenesjakoruzh
michal7kw

qdrant-mcp-ollama

by michal7kw
OverviewSchemaSourceRelated ServersDiscussionsAdmin
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를 참조하세요.

Available Tools

2 tools
qdrant_findC

Search for relevant information in the Qdrant database using semantic similarity.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language query to search for. The query is embedded using the same GPU model used for storage, ensuring accurate results.
top_kNoMaximum number of results to return (default: 5).
collection_nameNoName of the collection to search in. Required if no default collection is configured.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It implies a read-only operation but does not explicitly state that no data is modified, does not mention return behavior, error conditions, or limitations. The single sentence provides minimal behavioral disclosure beyond the literal action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundancy or filler. It is front-loaded with the verb and resource. While extremely brief, it is not a tautology and conveys the essential purpose. It avoids unnecessary words while being clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has a sibling (qdrant_store) and an output schema (which covers return format), the description is still incomplete. It lacks any usage context, such as when to choose this over storage or how the search integrates with the workflow. The presence of an output schema reduces the need to explain returns, but the description does not cover the selection decision or behavioral expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all three parameters (query, top_k, collection_name) with descriptions, so the baseline is 3. The description adds nothing beyond the schema; it mentions 'semantic similarity' which is already implied by the query parameter's embedding mention. No additional value is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Search'), the target resource ('Qdrant database'), and the method ('semantic similarity'). This distinguishes it from the sibling qdrant_store, which likely stores information. However, it does not explicitly name the sibling or contrast with it, so it lacks the full differentiation seen in higher-scoring examples.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the alternative qdrant_store, nor any mention of prerequisites or context. The description only states the action without any direction on selection or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

qdrant_storeC

Store information in the Qdrant database with GPU-accelerated embeddings.

ParametersJSON Schema
NameRequiredDescriptionDefault
metadataNoOptional metadata dictionary to attach to the stored point.
informationYesThe text information to store. This will be embedded and made searchable via semantic similarity.
collection_nameNoName of the collection to store in. Required if no default collection is configured.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that information will be stored with embeddings, but does not disclose potential side effects such as whether existing points are overwritten, whether collections are auto-created, or any error behavior. The mutation is implied but not explicitly flagged.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that conveys the core action. 'GPU-accelerated embeddings' adds a performance detail that may be useful context, but it could be considered extraneous. Overall, it is appropriately sized and front-loaded with the action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple store operation with only 3 parameters and an output schema present, the description covers the basic action. However, it omits guidance on when a collection_name is required and does not mention any setup steps or constraints. It meets a minimum viable level but leaves gaps that an agent might need to handle.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific detail beyond what the schema already provides. The only minor addition is implying that information gets embedded, which is already stated in the schema. This meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Store information in the Qdrant database') with a specific resource and purpose. It implies a write operation distinct from the sibling qdrant_find, though it doesn't explicitly differentiate. The mention of 'GPU-accelerated embeddings' adds implementation detail but doesn't obscure the core purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus the sibling qdrant_find. The description does not say 'use this to add data, use qdrant_find to search' or mention any prerequisites like collection existence. An agent would have to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedqdrant_find
    • First observedqdrant_store
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools, qdrant_store and qdrant_find, have entirely distinct purposes—one writes data, the other retrieves it. There is zero ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent 'qdrant_<verb>' pattern, using clear action verbs (store, find). The naming is predictable and uniform.

Tool Count3/5

With only two tools, the server feels thin for what is typically a database domain, but it is not an extreme mismatch. It sits at the borderline of adequacy.

Completeness2/5

The server only provides store and find, lacking any management operations like delete, update, or list. For a database, this is a significant gap that will limit workflow coverage.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers