Qdrant MCPサーバー

Qdrantベクトルデータベースと複数の埋め込みプロバイダーを使用してセマンティック検索機能を提供する、Model Context Protocol (MCP) サーバーです。

特徴

• セットアップ不要: 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 - セマンティック検索とハイブリッド検索の比較

• 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以上のファイルタイプ):

• Web: 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/ ディレクトリを参照してください:

• 基本的な使用方法 - コレクションの作成、ドキュメントの追加、検索

• **[ハイ