Skip to main content
Glama
dutchakdev

qdrant-mcp

by dutchakdev
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

qdrant-mcp

MCP server that gives AI coding agents persistent, semantic memory via Qdrant vector search.

Built for Claude Code but works with any MCP-compatible client.

"How does the price sync work?"

  ┌─ codebase ──────── sync-prices.ts (function syncFromAPI)
  ├─ documentation ─── API reference: POST /products/sync
  ├─ business_rules ── "Manual discounts override synced prices"
  └─ decisions ─────── ADR-007: Pull model chosen over webhooks

Key Features

Workspace-aware search — detects uncommitted changes via git status. Modified files return fresh content from disk, not stale embeddings. New files are discovered even before their first commit.

4 knowledge collections — code, documentation, business rules, architectural decisions. Search one or all at once.

Content-hashed indexing — only re-embeds chunks that actually changed. Full reindex of a large project takes seconds, not minutes.

Incremental by default — git post-commit hook triggers indexing of changed files in the background. Zero manual effort after setup.

Related MCP server: local-memory-mcp

Architecture

┌────────────────────────────────────────────────────────┐
│                  Claude Code Agent                      │
│                        │                               │
│                   MCP Protocol                         │
└────────────────────────┬───────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│               qdrant-mcp (this server)                  │
│                                                        │
│  Tools:                                                │
│    search_codebase   search_docs   search_business     │
│    search_decisions  search_all    reindex              │
│                                                        │
│  Workspace-Aware Layer:                                │
│  ┌──────────────┐ ┌───────────────┐ ┌───────────────┐  │
│  │WorkspaceState│→│FreshContent   │→│NewFiles       │  │
│  │ git status   │ │Resolver       │ │Matcher        │  │
│  │ dirty/new/del│ │ disk override │ │ path+keyword  │  │
│  └──────────────┘ └───────────────┘ └───────────────┘  │
└────────────────────────┬───────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│                   Qdrant (Docker)                       │
│                                                        │
│  ┌──────────┐ ┌──────────────┐ ┌────────────────────┐  │
│  │ codebase │ │documentation │ │ business_rules     │  │
│  └──────────┘ └──────────────┘ └────────────────────┘  │
│  ┌──────────────────┐                                  │
│  │    decisions      │                                  │
│  └──────────────────┘                                  │
└────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

  • Node.js >= 20

  • Docker (for Qdrant)

  • OpenAI API key (or Ollama for local embeddings)

Install

git clone https://github.com/dutchakdev/qdrant-mcp.git
cd qdrant-mcp
npm install
npm run build

Configure

cp .env.example .env

Edit .env:

QDRANT_URL=http://localhost:6333
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
PROJECT_ROOT=/path/to/your/project

Setup (one command)

npm run setup

This will:

  1. Start Qdrant via Docker Compose

  2. Create all 4 collections with proper indexes

  3. Run initial codebase indexing

  4. Install git post-commit hook

Connect to Claude Code

Add to your .claude/settings.json or claude_desktop_config.json:

{
  "mcpServers": {
    "project-knowledge": {
      "command": "node",
      "args": ["/absolute/path/to/qdrant-mcp/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project",
        "QDRANT_URL": "http://localhost:6333",
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

MCP Tools

Tool

Description

search_codebase

Semantic code search. Filters by language, project. Workspace-aware.

search_docs

Documentation search across all indexed sources.

search_business

Business rules and domain logic. Filter by domain.

search_decisions

Architectural decisions, ADRs, resolved issues.

search_all

Hybrid search across all collections at once.

reindex

Trigger re-indexing (full or changed mode).

How Workspace Awareness Works

The core problem: you edit a file, but Qdrant still has the old embedding. The agent gets stale context.

The solution is a 3-component pipeline that runs on every search:

WorkspaceState — calls git status --porcelain=v2 (cached 2s). Knows which files are modified, new, deleted, or renamed.

FreshContentResolver — if a Qdrant result points to a dirty file, reads the fresh version from disk and replaces the stale content. Tries to extract the same symbol (function/class) via regex for precision.

NewFilesMatcher — discovers relevant new files that Qdrant doesn't know about. Three-phase matching: path tokens → content keywords → (optional) on-the-fly embedding.

Overhead: ~10-30ms per search. Negligible compared to embedding + vector search latency.

See RACE-CONDITIONS.md for the full edge case matrix.

CLI

# One-time setup (Qdrant + collections + initial index + git hook)
npm run setup

# Index changed files (default: since last commit)
npm run index

# Full reindex
npm run index:full

# Watch mode (real-time indexing on file save)
npm run watch

# Show collection stats
npm run status

Embedding Providers

OpenAI (default)

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # 1536 dim, ~$0.02/1M tokens

Ollama (local, free)

EMBEDDING_PROVIDER=ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # 768 dim

Install the model first: ollama pull nomic-embed-text

Project Structure

src/
├── index.ts                 # MCP server entry point
├── cli.ts                   # CLI (setup, index, watch, status)
├── config.ts                # Environment-based configuration
├── types/
│   └── index.ts             # Shared type definitions
├── embeddings/
│   └── provider.ts          # OpenAI + Ollama embedding providers
├── qdrant/
│   ├── client.ts            # Qdrant client singleton + init
│   └── collections.ts       # Collection schemas + setup
├── indexers/
│   └── code-indexer.ts      # Code chunking + content-hashed indexing
├── search/
│   └── workspace-aware-search.ts  # Main search pipeline
├── workspace/
│   ├── workspace-state.ts         # Git status → dirty/new/deleted detection
│   ├── fresh-content-resolver.ts  # Stale → fresh content replacement
│   ├── new-files-matcher.ts       # New file discovery (path + keyword + embedding)
│   └── index.ts
└── tools/
    └── definitions.ts       # MCP tool schemas

Customization

Adding new collections

Edit src/qdrant/collections.ts to add a collection, then add a corresponding search tool in src/tools/definitions.ts and handler in src/index.ts.

Indexing non-code content

The documentation and business_rules collections are ready but need custom indexers for your data sources. Create an indexer in src/indexers/ following the CodeIndexer pattern.

Adjusting chunking

The code indexer uses regex-based chunking by default (functions, classes, exports). For more precise AST-based chunking, replace the regex patterns in code-indexer.ts with tree-sitter parsing.

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

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

Resources

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/dutchakdev/qdrant-mcp'

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