Qdrant MCP 서버

Qdrant 벡터 데이터베이스와 다중 임베딩 공급자를 사용하여 의미론적 검색 기능을 제공하는 MCP(Model Context Protocol) 서버입니다.

주요 기능

• 설정 불필요: Ollama와 즉시 연동 - API 키가 필요 없음

• 개인정보 보호 우선: 로컬 임베딩 및 벡터 저장소 - 데이터가 기기 외부로 유출되지 않음

• 코드 벡터화: AST 인식 청킹 및 의미론적 코드 검색을 통한 지능형 코드베이스 인덱싱

• Git 기록 검색: 과거 변경 사항, 수정 사항 및 패턴에 대한 의미론적 검색을 위해 커밋 기록 인덱싱

• 고급 검색: 컨텍스트 검색(코드 + Git 상관관계) 및 여러 저장소에 걸친 연합 검색

• 다중 공급자: Ollama(기본값), OpenAI, Cohere, Voyage AI 지원

• 하이브리드 검색: 의미론적 검색과 키워드 검색을 결합하여 더 나은 결과 제공

• 의미론적 검색: 메타데이터 필터링을 포함한 자연어 검색

• 증분 인덱싱: 효율적인 업데이트 - 변경된 파일만 다시 인덱싱

• 구성 가능한 프롬프트: 코드 변경 없이 가이드 워크플로우를 위한 사용자 지정 프롬프트 생성

• 속도 제한: 지수 백오프를 통한 지능형 스로틀링

• 전체 CRUD: 컬렉션 및 문서 생성, 검색, 관리

• 구조화된 로깅: 구성 가능한 로그 레벨을 갖춘 Pino 기반 JSON 로깅

• 유연한 배포: 로컬(stdio) 또는 원격 HTTP 서버로 실행

• API 키 인증: 보안이 적용된 Qdrant 인스턴스(Qdrant Cloud, API 키가 있는 자체 호스팅)에 연결

Related MCP server: MCP Qdrant Server with OpenAI Embeddings

빠른 시작

사전 요구 사항

• Node.js 22.x 또는 24.x

• Podman 또는 Docker(Compose 지원)

설치

# Clone and install
git clone https://github.com/mhalder/qdrant-mcp-server.git
cd qdrant-mcp-server

# Node 22.x
npm install

# Node 24.x (requires C++20 flag for native module compilation)
CXXFLAGS='-std=c++20' npm install

# Start services (choose one)
podman compose up -d   # Using Podman
docker compose up -d   # Using Docker

# Pull the embedding model
podman exec ollama ollama pull nomic-embed-text  # Podman
docker exec ollama ollama pull nomic-embed-text  # Docker

# Build
npm run build

구성

로컬 설정 (stdio 전송)

claude mcp add --transport stdio qdrant -- node /path/to/qdrant-mcp-server/build/index.js

또는 ~/.claude.json에 추가:

{
  "mcpServers": {
    "qdrant": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"]
    }
  }
}

Qdrant Cloud 또는 보안 인스턴스의 경우 --env QDRANT_API_KEY=your-key를 추가하거나 환경 설정에서 설정하십시오.

테스트:

Create a collection called "notes" and add a document about machine learning

예제 프롬프트 활성화: prompts.example.json을 prompts.json으로 복사하고 재시작하십시오. /prompt를 사용하여 사용 가능한 프롬프트를 나열할 수 있습니다.

원격 설정 (HTTP 전송)

⚠️ 보안 경고: 프로덕션 환경에서 HTTP 전송을 배포할 때:

• 항상 HTTPS가 적용된 리버스 프록시(nginx, Caddy) 뒤에서 실행하십시오.

• 프록시 수준에서 인증/인가를 구현하십시오.

• 방화벽을 사용하여 신뢰할 수 있는 네트워크로 접근을 제한하십시오.

• 보호 장치 없이 공용 인터넷에 직접 노출하지 마십시오.

• 프록시 수준에서 속도 제한을 구현하는 것을 고려하십시오.

• 서버 로그에서 의심스러운 활동을 모니터링하십시오.

서버 시작:

TRANSPORT_MODE=http HTTP_PORT=3000 node build/index.js

옵션 1: claude mcp add 사용

claude mcp add --transport http qdrant http://your-server:3000/mcp

옵션 2: ~/.claude.json에 추가

{
  "mcpServers": {
    "qdrant": {
      "type": "http",
      "url": "http://your-server:3000/mcp"
    }
  }
}

다른 공급자 사용:

"env": {
  "EMBEDDING_PROVIDER": "openai",  // or "cohere", "voyage"
  "OPENAI_API_KEY": "sk-...",      // provider-specific API key
  "QDRANT_URL": "http://localhost:6333"
}

변경 후 재시작하십시오.

모든 옵션은 아래 고급 구성 섹션을 참조하십시오.

도구

컬렉션 관리

문서 작업

코드 벡터화

Git 기록

고급 검색

리소스

• qdrant://collections - 모든 컬렉션 나열

• qdrant://collection/{name} - 컬렉션 세부 정보

구성 가능한 프롬프트

코드를 수정하지 않고 특정 사용 사례에 맞춘 사용자 지정 프롬프트를 생성하십시오. 프롬프트는 일반적인 작업을 위한 가이드 워크플로우를 제공합니다.

참고: 기본적으로 서버는 프로젝트 루트 디렉토리에서 prompts.json을 찾습니다. 파일이 존재하면 프롬프트가 자동으로 로드됩니다. PROMPTS_CONFIG_FILE 환경 변수를 사용하여 사용자 지정 경로를 지정할 수 있습니다.

설정

1. 프롬프트 구성 파일 생성 (예: 프로젝트 루트의 prompts.json):

   복사 및 사용자 지정할 수 있는 예제 구성은 prompts.example.json을 참조하십시오.

2. 서버 구성 (선택 사항 - 사용자 지정 경로에만 필요):

프로젝트 루트에 prompts.json을 배치하면 추가 구성이 필요하지 않습니다. 사용자 지정 경로를 사용하려면:

{
  "mcpServers": {
    "qdrant": {
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "PROMPTS_CONFIG_FILE": "/custom/path/to/prompts.json"
      }
    }
  }
}

3. AI 어시스턴트에서 프롬프트 사용:

Claude Code:

/mcp__qdrant__find_similar_docs papers "neural networks" 10

VSCode:

/mcp.qdrant.find_similar_docs papers "neural networks" 10

예제 프롬프트

다음 내용을 포함하여 즉시 사용 가능한 프롬프트는 prompts.example.json을 참조하십시오:

• setup_rag_collection - RAG 최적화 컬렉션 생성

• analyze_and_optimize - 컬렉션 통찰력 및 권장 사항

• compare_search_strategies - 의미론적 검색 vs 하이브리드 검색 비교

• migrate_to_hybrid - 컬렉션 마이그레이션 가이드

• debug_search_quality - 검색 품질 문제 해결

• build_knowledge_base - 메타데이터가 포함된 구조화된 문서

• index_git_history - 의미론적 검색을 위한 저장소 커밋 기록 인덱싱

• search_project_history - 기능 구현을 이해하기 위한 Git 기록 검색

• investigate_code_with_history - 컨텍스트 검색을 통한 코드 심층 분석

• cross_repo_search - 여러 저장소에 걸친 패턴 검색

• trace_feature_evolution - 시간 경과에 따른 기능 진화 추적

• security_audit_search - 보안 관련 코드 및 수정 사항 찾기

템플릿 구문

템플릿은 {{variable}} 자리 표시자를 사용합니다:

• 필수 인수는 반드시 제공되어야 합니다.

• 선택적 인수는 지정되지 않은 경우 기본값을 사용합니다.

• 알 수 없는 변수는 출력에 그대로 남습니다.

코드 벡터화

의미론적 코드 검색을 사용하여 코드베이스를 지능적으로 인덱싱하고 검색하십시오. AI 지원 개발, 코드 탐색 및 대규모 코드베이스 이해에 적합합니다.

주요 기능

• AST 인식 청킹: tree-sitter를 사용하여 함수/클래스 경계에서 지능적인 코드 분할

• 다중 언어 지원: TypeScript, Python, Java, Go, Rust, C++ 등을 포함한 35개 이상의 파일 유형

• 증분 업데이트: 빠른 업데이트를 위해 변경된 파일만 다시 인덱싱

• 스마트 무시 패턴: .gitignore, .dockerignore 및 사용자 지정 .contextignore 파일 준수

• 의미론적 검색: 관련 코드를 찾기 위한 자연어 쿼리

• 메타데이터 필터링: 파일 유형, 경로 패턴 또는 언어별 필터링

• 로컬 우선: 모든 처리가 로컬에서 수행됨 - 코드가 기기 외부로 유출되지 않음

빠른 시작

1. 코드베이스 인덱싱:

# Via Claude Code MCP tool
/mcp__qdrant__index_codebase /path/to/your/project

2. 코드 검색:

# Natural language search
/mcp__qdrant__search_code /path/to/your/project "authentication middleware"

# Filter by file type
/mcp__qdrant__search_code /path/to/your/project "database schema" --fileTypes .ts,.js

# Filter by path pattern
/mcp__qdrant__search_code /path/to/your/project "API endpoints" --pathPattern src/api/**

3. 변경 후 업데이트:

# Incrementally re-index only changed files
/mcp__qdrant__reindex_changes /path/to/your/project

사용 예시

TypeScript 프로젝트 인덱싱

// The MCP tool automatically:
// 1. Scans all .ts, .tsx, .js, .jsx files
// 2. Respects .gitignore patterns (skips node_modules, dist, etc.)
// 3. Chunks code at function/class boundaries
// 4. Generates embeddings using your configured provider
// 5. Stores in Qdrant with metadata (file path, line numbers, language)

index_codebase({
  path: "/workspace/my-app",
  forceReindex: false, // Set to true to re-index from scratch
});

// Output:
// ✓ Indexed 247 files (1,823 chunks) in 45.2s

인증 코드 검색

search_code({
  path: "/workspace/my-app",
  query: "how does user authentication work?",
  limit: 5,
});

// Results include file path, line numbers, and code snippets:
// [
//   {
//     filePath: "src/auth/middleware.ts",
//     startLine: 15,
//     endLine: 42,
//     content: "export async function authenticateUser(req: Request) { ... }",
//     score: 0.89,
//     language: "typescript"
//   },
//   ...
// ]

필터를 사용한 검색

// Only search TypeScript files
search_code({
  path: "/workspace/my-app",
  query: "error handling patterns",
  fileTypes: [".ts", ".tsx"],
  limit: 10,
});

// Only search in specific directories
search_code({
  path: "/workspace/my-app",
  query: "API route handlers",
  pathPattern: "src/api/**",
  limit: 10,
});

증분 재인덱싱

// After making changes to your codebase
reindex_changes({
  path: "/workspace/my-app",
});

// Output:
// ✓ Updated: +3 files added, ~5 files modified, -1 files deleted
// ✓ Chunks: +47 added, -23 deleted in 8.3s

인덱싱 상태 확인

get_index_status({
  path: "/workspace/my-app",
});

// Output:
// {
//   status: "indexed",      // "not_indexed" | "indexing" | "indexed"
//   isIndexed: true,        // deprecated: use status instead
//   collectionName: "code_a3f8d2e1",
//   chunksCount: 1823,
//   filesCount: 247,
//   lastUpdated: "2025-01-30T10:15:00Z",
//   languages: ["typescript", "javascript", "json"]
// }

지원되는 언어

프로그래밍 언어 (35개 이상의 파일 유형):

• 웹: TypeScript, JavaScript, Vue, Svelte

• 백엔드: Python, Java, Go, Rust, Ruby, PHP

• 시스템: C, C++, C#

• 모바일: Swift, Kotlin, Dart

• 함수형: Scala, Clojure, Haskell, OCaml

• 스크립팅: Bash, Shell, Fish

• 데이터: SQL, GraphQL, Protocol Buffers

• 구성: JSON, YAML, TOML, XML, Markdown

전체 목록 및 사용자 지정 옵션은 구성을 참조하십시오.

사용자 지정 무시 패턴

프로젝트 루트에 .contextignore 파일을 생성하여 무시할 추가 패턴을 지정하십시오:

# .contextignore
**/test/**
**/*.test.ts
**/*.spec.ts
**/fixtures/**
**/mocks/**
**/__tests__/**

모범 사례

1. 한 번 인덱싱, 증분 업데이트: 초기 인덱싱에는 index_codebase를 사용하고, 업데이트에는 reindex_changes를 사용하십시오.

2. 필터 사용: 더 나은 결과를 위해 fileTypes 및 pathPattern으로 검색 범위를 좁히십시오.

3. 의미 있는 쿼리: 찾고자 하는 내용을 설명하는 자연어를 사용하십시오 (예: "db" 대신 "database connection pooling").

4. 상태 먼저 확인: 검색 전 get_index_status를 사용하여 코드베이스가 인덱싱되었는지 확인하십시오.

5. 로컬 임베딩: 모든 것을 로컬에서 비공개로 유지하려면 Ollama(기본값)를 사용하십시오.

성능

최신 노트북(Apple M1/M2 등)에서의 일반적인 성능:

참고: 인덱싱 시간은 임베딩 공급자에 따라 다릅니다. Ollama(로컬)가 초기 인덱싱에 가장 빠릅니다.

Git 기록 검색

자연어를 사용하여 저장소의 Git 커밋 기록을 인덱싱하고 검색하십시오. 과거 수정 사항을 찾고, 변경 패턴을 이해하며, 이전 작업에서 배우는 데 적합합니다.

주요 기능

• 의미론적 커밋 검색: 자연어로 찾고자 하는 내용을 설명하여 커밋 찾기

• Conventional Commit 분류: 커밋 자동 분류 (feat, fix, refactor 등)

• 증분 업데이트: 효율적인 업데이트를 위해 새 커밋만 인덱싱

• 풍부한 필터링: 커밋 유형, 작성자 또는 날짜 범위별 필터링

• 메타데이터 추출: 변경된 파일, 삽입/삭제 및 전체 커밋 컨텍스트 포함

빠른 시작

1. 저장소의 Git 기록 인덱싱:

# Via Claude Code MCP tool
/mcp__qdrant__index_git_history /path/to/your/repo

2. 관련 커밋 검색:

# Natural language search
/mcp__qdrant__search_git_history /path/to/your/repo "fix authentication bug"

# Filter by commit type
/mcp__qdrant__search_git_history /path/to/your/repo "database optimization" --commitTypes fix,perf

# Filter by author
/mcp__qdrant__search_git_history /path/to/your/repo "API changes" --authors "john@example.com"

3. 인덱스 최신 상태 유지:

# Incrementally index only new commits
/mcp__qdrant__index_new_commits /path/to/your/repo

사용 사례

• 유사한 수정 사항 찾기: "이전의 인증 관련 null 포인터 문제는 어떻게 해결되었나요?"

• 패턴 이해: "데이터베이스 계층에 어떤 리팩토링이 수행되었나요?"

• 기록에서 학습: "API 엔드포인트 구현 예시를 보여주세요."

• 코드 고고학: "작년에 결제 시스템에 어떤 변경 사항이 있었나요?"

고급 검색

코드와 Git 기록 검색을 결합하여 코드베이스를 더 깊이 이해하십시오. 먼저 index_codebase와 index_git_history로 저장소를 인덱싱해야 합니다.

• 컨텍스트 검색: 자동 파일-커밋 상관관계를 사용하여 코드 + Git 기록을 함께 쿼리

• 연합 검색: RRF 순위를 사용하여 여러 저장소에 걸쳐 검색

자세한 사용법, 워크플로우 및 시나리오는 **고급 검색 예시**를 참조하십시오.

예시

자세한 가이드는 examples/ 디렉토리를 참조하십시오:

• 기본 사용법 - 컬렉션 생성, 문서 추가, 검색

• **[하이브리드 검색](examples/hybrid